cw.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
codewiki (cw.py) — 코드 프로젝트용 AI Wiki 툴킷의 결정론적 부분.

의존성: Python 3.8+ 표준 라이브러리만 사용. (universal-ctags가 있으면 C/C++ 정밀도 향상)

명령:
  cw.py init <프로젝트경로>     위키 골격(wiki/)과 설정(.codewiki/) 설치
  cw.py index [경로]            소스에서 사실(facts) 추출 → .codewiki/facts.db
  cw.py stubs [경로]            wiki/files/ 아래 파일 stub 자동 생성 (편집 금지 영역)
  cw.py map   [경로]            모듈 후보/중요 파일 요약 출력 (AI에게 줄 지도)
  cw.py lint  [경로]            위키 문서의 anchor·라벨·최신성 검사
  cw.py update [경로]           git diff 기반으로 낡은(stale) 문서 찾기 + 재색인
  cw.py update --mark-done      AI 갱신 완료 후 현재 커밋을 기준점으로 기록
  cw.py status [경로]           색인 상태 요약
  cw.py parse-report [경로]     파서가 코드를 얼마나 읽어냈는지 진단 + 권고
  cw.py try-macros [경로]       범인 매크로를 하나씩 지워보고 안전한 것만 고름
  cw.py install-skills [경로]   Claude Code 스킬 설치 (setup 이 자동으로 해줌)
  cw.py log [경로] [--gaps]     기록장 — 위키에 없어서 코드를 열어본 질문

설계 원칙:
  - 코드는 절대 위키로 복사하지 않는다. anchor(경로:라인, sym:경로#이름)로 참조만 한다.
  - 기계가 뽑은 사실(facts.db)은 갱신하지 않고 매번 재생성한다.
  - DB에 없다는 것은 "존재하지 않음"이 아니라 "확인 못 함"이다. (비대칭 규칙)
"""

import argparse
import ast
from collections import namedtuple
import bisect
import fnmatch
import hashlib
import json
import os
import re
import shutil
import sqlite3
import subprocess
import sys
import warnings
from pathlib import Path

TOOLKIT_DIR = Path(__file__).resolve().parent

LANG_BY_EXT = {
    ".py": "python",
    ".c": "c", ".h": "c",
    ".cpp": "cpp", ".cc": "cpp", ".cxx": "cpp",
    ".hpp": "cpp", ".hh": "cpp", ".hxx": "cpp", ".inl": "cpp",
    ".idl": "idl",
    ".fidl": "idl",  # Franca IDL(SOME/IP 계열) — interface 이름 추출 목적
}

DEFAULT_EXCLUDES = [
    ".git", ".codewiki", "wiki", "build", "cmake-build-*", "out", "dist",
    "__pycache__", ".venv", "venv", "node_modules", "third_party", "external",
    ".idea", ".vscode",
]

# 파일 이름 기준 제외 — 생성 코드와 코드 생성용 템플릿.
# 사람이 문서화할 대상이 아니고, 파싱해봐야 오류만 쌓이며,
# 파일 수를 부풀려 커버리지 비율까지 왜곡한다.
# (.codewiki/config.json 의 "exclude_files" 로 덮어쓸 수 있다)
DEFAULT_EXCLUDE_FILES = [
    "*.pb.h", "*.pb.cc", "*.pb.c",        # protobuf 생성 코드
    "*.pb-c.h", "*.pb-c.c",               # protobuf-c
    "*.in.c", "*.in.h", "*.in.cpp", "*.in.hpp",   # 코드 생성 템플릿 (C 문법 아님)
    "*_generated.h", "*_generated.cc",    # flatbuffers 등
    "moc_*.cpp", "ui_*.h", "qrc_*.cpp",   # Qt 생성 코드
    "*.pyc",
]

# ---------------------------------------------------------------- 공통 유틸

def die(msg):
    print("오류: " + msg, file=sys.stderr)
    sys.exit(1)


def sha_of(data: bytes) -> str:
    return hashlib.sha1(data).hexdigest()[:12]


def read_source(p: Path):
    """소스 파일 읽기. UTF-8 → CP949(한국어 레거시) → latin-1 순서로 시도.
    반환: (raw bytes, 디코딩된 text, 사용된 인코딩)"""
    raw = p.read_bytes()
    for enc in ("utf-8", "cp949", "latin-1"):
        try:
            return raw, raw.decode(enc), enc
        except UnicodeDecodeError:
            continue
    return raw, raw.decode("utf-8", errors="replace"), "utf-8(replace)"


def run_git(root: Path, *args):
    """git 명령 실행. git 저장소가 아니거나 실패하면 None."""
    try:
        r = subprocess.run(["git", "-C", str(root)] + list(args),
                           capture_output=True, text=True, timeout=30)
        if r.returncode != 0:
            return None
        return r.stdout.strip()
    except Exception:
        return None


def load_config(root: Path) -> dict:
    cfg_path = root / ".codewiki" / "config.json"
    cfg = {"exclude_dirs": DEFAULT_EXCLUDES, "extra_source_dirs": [],
           "ignore_macros": []}
    if cfg_path.exists():
        try:
            cfg.update(json.loads(cfg_path.read_text(encoding="utf-8")))
        except Exception as e:
            die(f"config.json 파싱 실패: {e}")
    return cfg


def is_excluded(rel_parts, patterns):
    for part in rel_parts:
        for pat in patterns:
            if fnmatch.fnmatch(part, pat):
                return True
    return False


_LAST_SKIPPED_GENERATED = 0   # 직전 iter_source_files 가 건너뛴 생성 코드 수


def iter_source_files(root: Path, cfg: dict):
    global _LAST_SKIPPED_GENERATED
    _LAST_SKIPPED_GENERATED = 0
    excludes = cfg.get("exclude_dirs", DEFAULT_EXCLUDES)
    file_excludes = cfg.get("exclude_files", DEFAULT_EXCLUDE_FILES)
    for dirpath, dirnames, filenames in os.walk(root):
        rel = Path(dirpath).relative_to(root)
        dirnames[:] = [d for d in dirnames
                       if not is_excluded([d], excludes)]
        if rel.parts and is_excluded(rel.parts, excludes):
            dirnames[:] = []
            continue
        for fn in sorted(filenames):
            ext = Path(fn).suffix.lower()
            if ext not in LANG_BY_EXT:
                continue
            if any(fnmatch.fnmatch(fn, pat) for pat in file_excludes):
                _LAST_SKIPPED_GENERATED += 1
                continue
            yield Path(dirpath) / fn


def db_path(root: Path) -> Path:
    return root / ".codewiki" / "facts.db"


def open_db(root: Path, create=False) -> sqlite3.Connection:
    p = db_path(root)
    if not p.exists() and not create:
        die("facts.db가 없습니다. 먼저 `cw.py index`를 실행하세요.")
    p.parent.mkdir(parents=True, exist_ok=True)
    con = sqlite3.connect(str(p))
    con.execute("PRAGMA journal_mode=WAL")
    return con


SCHEMA = """
CREATE TABLE IF NOT EXISTS files(
  id INTEGER PRIMARY KEY, path TEXT UNIQUE, sha TEXT, lang TEXT, loc INTEGER);
CREATE TABLE IF NOT EXISTS symbols(
  id INTEGER PRIMARY KEY, file_id INTEGER, name TEXT, kind TEXT,
  signature TEXT, line_start INTEGER, line_end INTEGER, provenance TEXT);
CREATE TABLE IF NOT EXISTS edges(
  id INTEGER PRIMARY KEY, src_file TEXT, src_symbol TEXT,
  dst_name TEXT, dst_file TEXT, kind TEXT, provenance TEXT, confidence TEXT);
CREATE TABLE IF NOT EXISTS gaps(
  id INTEGER PRIMARY KEY, file TEXT, line INTEGER, kind TEXT,
  detail TEXT, affects_symbol TEXT,
  status TEXT NOT NULL DEFAULT 'open', resolution TEXT, evidence TEXT);
CREATE INDEX IF NOT EXISTS idx_gap_file ON gaps(file);
CREATE INDEX IF NOT EXISTS idx_gap_sym ON gaps(affects_symbol);
CREATE INDEX IF NOT EXISTS idx_gap_kind ON gaps(kind);
CREATE INDEX IF NOT EXISTS idx_sym_file ON symbols(file_id);
CREATE INDEX IF NOT EXISTS idx_edge_src ON edges(src_file);
CREATE INDEX IF NOT EXISTS idx_edge_dst ON edges(dst_file);
CREATE INDEX IF NOT EXISTS idx_edge_dstname ON edges(dst_name);
CREATE INDEX IF NOT EXISTS idx_sym_name ON symbols(name);
"""

# ---------------------------------------------------------------- 파서들
# 원칙: 여기서 뽑은 것은 "찾은 사실"이다. 못 찾은 것은 없다는 뜻이 아니다.

def parse_python(path: Path, text: str):
    """stdlib ast 사용 — python 심볼/임포트는 신뢰도 높음(confirmed)."""
    symbols, edges = [], []
    try:
        # 색인 대상 파일의 문법 경고(invalid escape sequence 등)는
        # 그 프로젝트의 문제이지 색인 오류가 아니므로 출력하지 않는다.
        with warnings.catch_warnings():
            warnings.simplefilter("ignore")
            tree = ast.parse(text)
    except SyntaxError:
        return symbols, edges
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            args = ", ".join(a.arg for a in node.args.args)
            symbols.append((node.name, "function", f"def {node.name}({args})",
                            node.lineno, getattr(node, "end_lineno", node.lineno),
                            "python-ast"))
            for sub in ast.walk(node):
                if isinstance(sub, ast.Call):
                    fn = sub.func
                    callee = None
                    if isinstance(fn, ast.Name):
                        callee = fn.id
                    elif isinstance(fn, ast.Attribute):
                        callee = fn.attr
                    if callee:
                        # 이름 기반 호출: 어느 심볼로 가는지는 미해석 → inferred
                        edges.append((node.name, callee, None, "calls",
                                      "python-ast", "inferred"))
        elif isinstance(node, ast.ClassDef):
            bases = ", ".join(getattr(b, "id", getattr(b, "attr", "?"))
                              for b in node.bases)
            symbols.append((node.name, "class", f"class {node.name}({bases})",
                            node.lineno, getattr(node, "end_lineno", node.lineno),
                            "python-ast"))
        elif isinstance(node, ast.Import):
            for alias in node.names:
                edges.append((None, alias.name, None, "imports",
                              "python-ast", "confirmed"))
        elif isinstance(node, ast.ImportFrom):
            mod = node.module or ""
            edges.append((None, mod, None, "imports", "python-ast", "confirmed"))
    return symbols, edges


RE_INCLUDE = re.compile(r'^\s*#\s*include\s*[<"]([^">]+)[">]', re.M)
RE_CLASS = re.compile(r'^\s*(?:template\s*<[^>]*>\s*)?(class|struct)\s+(\w+)'
                      r'(?![^{;\n]*;)', re.M)
# ---- C/C++ 스캐너 (정규식 휴리스틱 대체) ----------------------------------
# 방식: 주석·문자열·전처리 줄을 공백으로 지운 뒤(줄 번호 보존),
# 모든 '{'에 대해 바로 앞이 "이름(인자들)" 형태인지 뒤로 검사한다.
# 정규식 대비 개선: 여러 줄 시그니처, 생성자 초기화 리스트, 함수 끝 라인,
# 주석/문자열 속 가짜 코드 오탐 제거. 여전히 못 하는 것: 매크로 전개,
# 템플릿 인스턴스 해석, operator 오버로드 일부.

C_STRIP_RE = re.compile(
    r'R"([^(\n]{0,16})\([\s\S]*?\)\1"'        # C++11 raw string
    r'|//[^\n]*'                              # 줄 주석
    r'|/\*[\s\S]*?\*/'                        # 블록 주석
    r'|"(?:\\.|[^"\\\n])*"'                   # 문자열
    r"|'(?:\\.|[^'\\\n])*'"                   # 문자
    r'|^[ \t]*#[^\n]*(?:\\\n[^\n]*)*',        # 전처리 지시문(#define의 { 방지)
    re.M)

CTRL_KEYWORDS = {"if", "for", "while", "switch", "return", "else", "do",
                 "case", "catch", "sizeof", "new", "delete", "defined",
                 "assert", "constexpr", "requires", "alignas", "decltype",
                 "alignof", "static_assert", "typeid"}
TRAILER_WORDS = {"const", "noexcept", "override", "final", "mutable",
                 "volatile", "throw", "try"}


def _blank_keep_newlines(m):
    return "".join(c if c == "\n" else " " for c in m.group(0))


def blank_macros(text, names):
    """장식 매크로 이름을 같은 길이의 공백으로 지운다.

    `MEDIA_PUBLIC void start_camera(int)` 처럼 타입 자리 앞에 붙는 매크로는
    파서를 깨뜨려 선언 전체를 놓치게 만든다. 무엇으로 전개되는지는 알 필요가
    없다 — 지우기만 하면 나머지가 그대로 읽힌다. (사내 실측: MEDIA_PUBLIC
    1,002곳, ADSTDTFSIMD_FORCE_INLINE 254곳)

    같은 길이의 공백으로 바꾸는 이유: 줄·열 번호가 원본과 어긋나면 구멍의
    위치와 심볼의 줄 번호가 전부 틀어진다.

    전처리기 지시문 줄(`#define`/`#ifdef`/`#undef`)은 건드리지 않는다.
    정의 자체에서 이름을 지우면 그 줄이 새 오류가 된다.
    """
    if not names:
        return text
    names = [n for n in names if n]
    if not names:
        return text
    # 긴 이름부터 — C_VEC_MEM 이 C_VEC_MEM_EXT 의 앞부분을 먼저 먹으면 안 된다
    rx = re.compile(r"\b(?:%s)\b" % "|".join(
        re.escape(n) for n in sorted(set(names), key=len, reverse=True)))
    out = []
    for line in text.split("\n"):
        if line.lstrip().startswith("#"):
            out.append(line)
        else:
            out.append(rx.sub(lambda m: " " * len(m.group(0)), line))
    return "\n".join(out)


def _match_back(s, i, close_ch, open_ch, limit_chars=6000):
    """s[i]==close_ch에서 짝이 되는 open_ch 인덱스. 실패/한도 초과 시 -1."""
    depth = 0
    limit = max(0, i - limit_chars)
    while i >= limit:
        c = s[i]
        if c == close_ch:
            depth += 1
        elif c == open_ch:
            depth -= 1
            if depth == 0:
                return i
        i -= 1
    return -1


def _ident_back(s, i):
    """s[i]에서 뒤로 (한정 가능한) 식별자 읽기 → (name, name_start_index)."""
    j = i
    while j >= 0:
        c = s[j]
        if c.isalnum() or c in "_~":
            j -= 1
        elif c == ":" and j >= 1 and s[j - 1] == ":":
            j -= 2
        else:
            break
    return s[j + 1:i + 1], j + 1


def _is_access_colon(s, k):
    """s[k]==':' 가 public:/private:/protected: 의 콜론인지."""
    if k < 1:
        return False
    word, _ = _ident_back(s, k - 1)
    return word in ("public", "private", "protected")


def _sig_before_brace(s, brace_pos):
    """'{' 직전이 함수 시그니처면 (name, name_pos, sig) 반환, 아니면 None."""
    i = brace_pos - 1
    for _ in range(40):  # 초기화 리스트 멤버 수 상한
        while i >= 0 and s[i].isspace():
            i -= 1
        if i < 0:
            return None
        c = s[i]
        if c == ")":
            op = _match_back(s, i, ")", "(")
            if op < 0:
                return None
            j = op - 1
            while j >= 0 and s[j].isspace():
                j -= 1
            if j < 0:
                return None
            name, ns = _ident_back(s, j)
            if not name:
                return None  # 람다 `](){...}`, 캐스팅 등
            base = name.split("::")[-1].lstrip("~")
            if base in TRAILER_WORDS:  # noexcept(...) 같은 꼬리 그룹
                i = ns - 1
                continue
            if base in CTRL_KEYWORDS:
                return None
            # 생성자 초기화 리스트 항목( `: a_(1), b_(2)` )이면 더 뒤로.
            # 단 `public:` 등 접근 지정자의 콜론은 초기화 리스트가 아니다.
            k = ns - 1
            while k >= 0 and s[k].isspace():
                k -= 1
            if k >= 0 and (s[k] == "," or
                           (s[k] == ":" and (k == 0 or s[k - 1] != ":")
                            and not _is_access_colon(s, k))):
                i = k - 1
                continue
            sig = re.sub(r"\s+", " ", s[ns:i + 1]).strip()
            return name, ns, sig[:120]
        if c == "}":  # 초기화 리스트의 brace-init `count_{0}` 건너뛰기
            op = _match_back(s, i, "}", "{")
            if op < 0:
                return None
            i = op - 1
            continue
        if c.isalnum() or c == "_":
            name, ns = _ident_back(s, i)
            if name in TRAILER_WORDS:
                i = ns - 1
                continue
            if name.split("::")[-1] in CTRL_KEYWORDS:
                return None  # `return {};` 등
            arrow = s.rfind("->", max(0, ns - 200), ns)
            if arrow >= 0:  # 후행 반환 타입 `-> std::vector<int>`
                i = arrow - 1
                continue
            # 초기화 리스트의 brace-init 멤버 이름( `count_{0}` 의 count_ )
            k = ns - 1
            while k >= 0 and s[k].isspace():
                k -= 1
            if k >= 0 and (s[k] == "," or
                           (s[k] == ":" and (k == 0 or s[k - 1] != ":"))):
                i = k - 1
                continue
            return None
        if c in ">&*:":
            arrow = s.rfind("->", max(0, i - 200), i)
            if arrow >= 0:
                i = arrow - 1
                continue
            return None
        return None
    return None


CALL_RE = re.compile(r"\b([A-Za-z_]\w{1,63})\s*\(")
CALL_NOISE = CTRL_KEYWORDS | TRAILER_WORDS | {
    "int", "char", "float", "double", "void", "bool", "long", "short",
    "unsigned", "signed", "auto", "size_t", "template", "operator",
    "static_cast", "dynamic_cast", "reinterpret_cast", "const_cast"}
MAX_CALLS_PER_FUNC = 32


def _find_functions(stripped):
    nl = [m.start() for m in re.finditer("\n", stripped)]

    def line_of(pos):
        return bisect.bisect_left(nl, pos) + 1

    stack, pairs = [], {}
    for m in re.finditer(r"[{}]", stripped):
        if m.group() == "{":
            stack.append(m.start())
        elif stack:
            pairs[stack.pop()] = m.start()
    out, calls, seen = [], [], set()
    for p in sorted(pairs):
        hit = _sig_before_brace(stripped, p)
        if hit:
            name, ns, sig = hit
            if ns in seen:  # 초기화 리스트의 brace-init 등 내부 '{' 중복 방지
                continue
            seen.add(ns)
            out.append((name, "function", sig,
                        line_of(ns), line_of(pairs[p]), "scanner"))
            # 본문 속 호출 후보: `이름(` 패턴 — 어느 심볼로 가는지는 미해석
            body = stripped[p:pairs[p]]
            base = name.split("::")[-1]
            found = set()
            for cm in CALL_RE.finditer(body):
                callee = cm.group(1)
                if callee in CALL_NOISE or callee == base:
                    continue
                found.add(callee)
                if len(found) >= MAX_CALLS_PER_FUNC:
                    break
            for callee in sorted(found):
                calls.append((name, callee, None, "calls",
                              "scanner", "inferred"))
    return out, calls


def parse_c_cpp(path: Path, text: str):
    """스캐너 휴리스틱 — 컴파일하지 않으므로 매크로 전개·템플릿 해석은 못 하고,
    그 사실을 provenance='scanner'로 기록한다. universal-ctags가 있으면 대체됨."""
    symbols, edges = [], []
    for m in RE_INCLUDE.finditer(text):  # 전처리 줄은 원본에서 추출
        edges.append((None, m.group(1), None, "includes", "regex", "confirmed"))
    stripped = C_STRIP_RE.sub(_blank_keep_newlines, text)
    for m in RE_CLASS.finditer(stripped):
        line = stripped.count("\n", 0, m.start()) + 1
        symbols.append((m.group(2), m.group(1), m.group(0).strip()[:120],
                        line, line, "scanner"))
    funcs, calls = _find_functions(stripped)
    symbols += funcs
    edges += calls
    return symbols, edges


def parse_c_cpp_ctags(path: Path, text: str):
    """universal-ctags(JSON 출력 지원)가 있으면 사용 — regex보다 정확."""
    try:
        r = subprocess.run(
            ["ctags", "--output-format=json", "--fields=+neS",
             "--languages=C,C++", "-f", "-", str(path)],
            capture_output=True, text=True, timeout=30)
        if r.returncode != 0:
            return None
    except Exception:
        return None
    symbols = []
    kind_map = {"function": "function", "class": "class", "struct": "struct",
                "member": "method", "prototype": "prototype",
                "enum": "enum", "typedef": "typedef"}
    for line in r.stdout.splitlines():
        try:
            t = json.loads(line)
        except Exception:
            continue
        kind = kind_map.get(t.get("kind"))
        if not kind:
            continue
        ln = t.get("line", 0)
        symbols.append((t.get("name", "?"), kind,
                        (t.get("signature") or t.get("pattern") or "")[:120],
                        ln, t.get("end", ln), "ctags"))
    edges = [(None, m.group(1), None, "includes", "regex", "confirmed")
             for m in RE_INCLUDE.finditer(text)]
    return symbols, edges


RE_IDL_MODULE = re.compile(r'^\s*module\s+(\w+)', re.M)
RE_IDL_IFACE = re.compile(r'^\s*(?:abstract\s+|local\s+)?interface\s+(\w+)', re.M)
RE_IDL_STRUCT = re.compile(r'^\s*struct\s+(\w+)', re.M)
RE_IDL_ENUM = re.compile(r'^\s*enum\s+(\w+)', re.M)
RE_IDL_TYPEDEF = re.compile(r'^\s*typedef\s+[\w:<>,\s]+?(\w+)\s*(?:\[[^\]]*\])?\s*;', re.M)
RE_IDL_METHOD = re.compile(
    r'^\s*(?:oneway\s+)?(?:void|[\w:]+(?:\s*<[^>]*>)?)\s+(\w+)\s*\(', re.M)
IDL_METHOD_BLACKLIST = {"module", "interface", "struct", "enum", "typedef",
                        "exception", "union", "switch", "case", "if"}


def parse_idl(path: Path, text: str):
    """CORBA/DDS IDL — 문법이 단순해 정규식으로도 신뢰도가 상당히 높음."""
    symbols, edges = [], []
    for m in RE_INCLUDE.finditer(text):
        edges.append((None, m.group(1), None, "includes", "regex", "confirmed"))
    for rx, kind in [(RE_IDL_MODULE, "idl_module"), (RE_IDL_IFACE, "idl_interface"),
                     (RE_IDL_STRUCT, "idl_struct"), (RE_IDL_ENUM, "idl_enum"),
                     (RE_IDL_TYPEDEF, "idl_typedef")]:
        for m in rx.finditer(text):
            line = text.count("\n", 0, m.start()) + 1
            symbols.append((m.group(1), kind, m.group(0).strip()[:120],
                            line, line, "regex"))
    declared = {s[0] for s in symbols}
    for m in RE_IDL_METHOD.finditer(text):
        name = m.group(1)
        if name in IDL_METHOD_BLACKLIST or name in declared:
            continue
        line = text.count("\n", 0, m.start()) + 1
        symbols.append((name, "idl_method", m.group(0).strip()[:120],
                        line, line, "regex"))
    return symbols, edges


_HAS_UCTAGS = None

def has_universal_ctags():
    global _HAS_UCTAGS
    if _HAS_UCTAGS is None:
        try:
            r = subprocess.run(["ctags", "--version"], capture_output=True,
                               text=True, timeout=10)
            _HAS_UCTAGS = "Universal Ctags" in (r.stdout or "")
        except Exception:
            _HAS_UCTAGS = False
    return _HAS_UCTAGS


# ---------------------------------------------------------------- tree-sitter
# 교체 이유는 정확도가 아니라 "못 읽은 것을 말해주는 능력"이다.
# 정규식 스캐너는 못 읽으면 조용히 넘어가므로, 자기가 뭘 놓쳤는지 모른다.
# tree-sitter는 해석 실패를 ERROR/MISSING 노드로 알려주고, 그것이
# 미해석 대장(gaps)의 재료가 된다.

_TS_CACHE = None   # (languages_or_None, reason)


def _ts_load():
    """tree-sitter 로드 시도. 실패해도 예외를 밖으로 내보내지 않는다."""
    try:
        from tree_sitter import Language, Parser  # noqa: F401
    except ImportError:
        return None, ("tree-sitter 미설치 → 내장 정규식 파서 사용. "
                      "정밀 모드를 쓰려면: pip install -r requirements-parser.txt")
    try:
        import tree_sitter_c
        import tree_sitter_cpp
    except ImportError:
        return None, ("tree-sitter 문법 패키지 미설치 → 내장 정규식 파서 사용. "
                      "pip install -r requirements-parser.txt")
    try:
        from tree_sitter import Language, Parser
        langs = {"c": Language(tree_sitter_c.language()),
                 "cpp": Language(tree_sitter_cpp.language())}
        Parser(langs["c"])          # ABI 호환성은 여기서 터진다
        return langs, "tree-sitter 사용 가능 (정밀 모드)"
    except Exception as e:
        return None, (f"tree-sitter 버전 충돌 → 내장 정규식 파서 사용 ({e}). "
                      "requirements-parser.txt 의 핀 버전으로 맞추세요: "
                      "pip install -r requirements-parser.txt")


def _ts_get():
    global _TS_CACHE
    if _TS_CACHE is None:
        _TS_CACHE = _ts_load()
    return _TS_CACHE


def ts_languages():
    """{'c': Language, 'cpp': Language} 또는 None."""
    return _ts_get()[0]


def ts_status():
    """(사용가능여부, 사람이 읽는 사유)."""
    langs, reason = _ts_get()
    return (langs is not None), reason


_TS_NAME_NODES = ("identifier", "field_identifier", "qualified_identifier",
                  "operator_name", "destructor_name", "type_identifier")

# C 관례상 매크로는 대문자다. 파싱 오류가 난 줄의 대문자 식별자를 모으면
# "무엇 때문에 못 읽었나"의 후보가 나온다. 완벽한 판별은 아니지만
# "다음에 뭘 처리할지"를 정하는 데는 충분하다.
_MACROISH_RE = re.compile(r"\b([A-Z][A-Z0-9_]{2,})\b")

# 매크로 모양이지만 범인일 리 없는 흔한 상수·타입 — 빼지 않으면 목록이 이걸로 덮인다
_MACROISH_IGNORE = {
    "NULL", "TRUE", "FALSE", "EOF", "SEEK_SET", "SEEK_CUR", "SEEK_END",
    "INT_MAX", "INT_MIN", "UINT_MAX", "LONG_MAX", "SIZE_MAX", "CHAR_BIT",
    "UINT8_MAX", "UINT16_MAX", "UINT32_MAX", "UINT64_MAX",
    "INT8_MAX", "INT16_MAX", "INT32_MAX", "INT64_MAX",
    "M_PI", "RAND_MAX", "BUFSIZ", "STDIN_FILENO", "STDOUT_FILENO",
    "STDERR_FILENO", "EXIT_SUCCESS", "EXIT_FAILURE",
}


def _culprit_macros(lines, line_idx):
    """오류가 난 줄(과 바로 앞줄)에서 매크로 후보를 뽑는다.

    선언이 여러 줄에 걸칠 수 있어 앞줄까지 본다.
    """
    lo = max(0, line_idx - 1)
    ctx = "\n".join(lines[lo:line_idx + 1])
    out = []
    for m in _MACROISH_RE.findall(ctx):
        if m not in _MACROISH_IGNORE and m not in out:
            out.append(m)
    return out[:4]      # 한 오류당 최대 4개까지만


def _ts_is_include_guard(node, src):
    """인클루드 가드(#ifndef FOO_H / #define FOO_H)인가?

    가드는 거의 모든 헤더에 있으므로 이걸 조건부 컴파일 구멍으로 세면
    판정이 항상 '나쁨'이 되고 커버리지 경고가 노이즈가 되어 무시당한다.
    가드는 빌드 변형이 아니라 관용구이므로 제외한다.

    판별: 최상위 preproc_ifdef 이면서 #else 가 없고,
          안쪽 첫 지시문이 같은 이름의 #define 인 것.
    """
    if node.type != "preproc_ifdef":
        return False
    if node.parent is None or node.parent.type != "translation_unit":
        return False
    if node.child_by_field_name("alternative") is not None:
        return False
    nm = node.child_by_field_name("name")
    if nm is None:
        return False
    guard = src[nm.start_byte:nm.end_byte].decode("utf-8", "replace")
    for ch in node.children:
        if ch.type in ("preproc_def", "preproc_function_def"):
            d = ch.child_by_field_name("name")
            return (d is not None and
                    src[d.start_byte:d.end_byte].decode(
                        "utf-8", "replace") == guard)
        if ch.type not in ("#ifndef", "#ifdef", "identifier", "comment"):
            return False
    return False


def _ts_decl_name(node, src):
    """function_definition 에서 (이름, 매크로로_뭉개짐) 추출.

    매크로가 시그니처에 끼면 tree-sitter 는 declarator 를
    parenthesized_declarator 로 파싱한다. 이때 진짜 이름은 그 앞의
    type_identifier 에 들어간다. 예:
        FUNC(void, RTE_CODE) Rte_Write_Sig(VAR(uint8, AUTOMATIC) v)
        → type_identifier[Rte_Write_Sig] + parenthesized_declarator[(...)]
    이 모양은 ERROR 노드 없이도 나타나므로 has_error 만으로는 못 잡는다.
    """
    d = node.child_by_field_name("declarator")
    while d is not None:
        if d.type == "parenthesized_declarator":
            for ch in node.children:
                if ch is d:
                    break
                if ch.type == "type_identifier":
                    return src[ch.start_byte:ch.end_byte].decode(
                        "utf-8", "replace"), True
            return None, True
        if d.type in _TS_NAME_NODES:
            return src[d.start_byte:d.end_byte].decode("utf-8", "replace"), False
        nxt = d.child_by_field_name("declarator")
        if nxt is None:
            for ch in d.children:
                if ch.type in _TS_NAME_NODES:
                    return src[ch.start_byte:ch.end_byte].decode(
                        "utf-8", "replace"), False
            return None, True
        d = nxt
    return None, True


def parse_c_cpp_ts(path: Path, text: str, lang: str):
    """tree-sitter 파서. (symbols, edges, gaps) 반환. 불가 시 None.

    gaps 항목은 (kind, line, detail, affects_symbol) 4-튜플.
    """
    langs = ts_languages()
    if langs is None:
        return None
    from tree_sitter import Parser
    src = text.encode("utf-8", "replace")
    try:
        tree = Parser(langs["cpp" if lang == "cpp" else "c"]).parse(src)
    except Exception:
        return None

    symbols, edges, gaps = [], [], []
    guard_names = set()   # 인클루드 가드의 #define 은 심볼이 아니다
    text_lines = text.split("\n")

    def txt(n):
        return src[n.start_byte:n.end_byte].decode("utf-8", "replace")

    def _decl_ident(node):
        """declaration/declarator 사슬을 타고 내려가 이름 노드를 찾는다."""
        d = node
        seen = 0
        while d is not None and seen < 12:
            seen += 1
            if d.type in _TS_NAME_NODES:
                return d
            nxt = d.child_by_field_name("declarator")
            if nxt is None:
                for ch in d.children:
                    if ch.type in _TS_NAME_NODES:
                        return ch
                return None
            d = nxt
        return None

    def walk(n, enclosing, in_func=False):
        line = n.start_point[0] + 1
        cur = enclosing

        # ERROR/MISSING 은 별도 if 로 둔다. elif 로 묶으면 ERROR 노드 안의
        # 함수 정의를 놓친다.
        if n.is_missing:
            gaps.append(("parse_missing", line,
                         "문법상 빠진 토큰 '%s' — 매크로 때문일 수 있음" % n.type,
                         None,
                         ",".join(_culprit_macros(text_lines, n.start_point[0]))))
        elif n.is_error:
            gaps.append(("parse_error", line,
                         "이 구간을 문법으로 해석하지 못함", None,
                         ",".join(_culprit_macros(text_lines, n.start_point[0]))))

        if n.type == "function_definition":
            name, mangled = _ts_decl_name(n, src)
            if name:
                symbols.append((name, "function",
                                txt(n).split("{")[0].strip()[:120],
                                line, n.end_point[0] + 1, "tree-sitter"))
                cur = name
            if mangled:
                gaps.append(("macro_mangled_decl", line,
                             "매크로가 시그니처를 가림 — 실제 이름이 다를 수 있음",
                             name,
                             ",".join(_culprit_macros(text_lines,
                                                      n.start_point[0]))))
        elif n.type in ("class_specifier", "struct_specifier", "enum_specifier",
                        "union_specifier"):
            nm = n.child_by_field_name("name")
            if nm is not None:
                kind = {"class_specifier": "class", "struct_specifier": "struct",
                        "enum_specifier": "enum", "union_specifier": "union"}[n.type]
                symbols.append((txt(nm), kind, txt(n).split("{")[0].strip()[:120],
                                line, n.end_point[0] + 1, "tree-sitter"))
        # --- C 헤더의 실체는 '선언'이다. 정의만 뽑으면 헤더가 통째로 안 보인다.
        elif n.type == "enumerator":
            nm = n.child_by_field_name("name")
            if nm is None:
                nm = next((c for c in n.children if c.type == "identifier"), None)
            if nm is not None:
                symbols.append((txt(nm), "enum_constant", txt(n).strip()[:120],
                                line, n.end_point[0] + 1, "tree-sitter"))
        elif n.type == "type_definition":
            # typedef enum {...} a_e;  /  typedef unsigned int id_t;
            # 이름은 마지막 직계 type_identifier 다 (앞쪽 것은 원본 타입 이름).
            names = [c for c in n.children if c.type == "type_identifier"]
            if names:
                symbols.append((txt(names[-1]), "typedef",
                                txt(n).replace("\n", " ")[:120],
                                line, n.end_point[0] + 1, "tree-sitter"))
        elif n.type == "preproc_def":
            nm = n.child_by_field_name("name")
            if nm is not None and txt(nm) not in guard_names:
                symbols.append((txt(nm), "macro", txt(n).replace("\n", " ")[:120],
                                line, n.end_point[0] + 1, "tree-sitter"))
        elif n.type == "preproc_function_def":
            nm = n.child_by_field_name("name")
            if nm is not None:
                symbols.append((txt(nm), "macro_fn", txt(n).replace("\n", " ")[:120],
                                line, n.end_point[0] + 1, "tree-sitter"))
        elif n.type == "declaration" and not in_func:
            # 함수 밖에서만 기록한다. 안 그러면 지역변수가 전부 심볼이 되어
            # 노이즈로 못 쓰게 된다.
            d = n.child_by_field_name("declarator")
            is_proto = False
            probe = d
            for _ in range(8):
                if probe is None:
                    break
                if probe.type == "function_declarator":
                    is_proto = True
                    break
                probe = probe.child_by_field_name("declarator")
            ident = _decl_ident(d) if d is not None else None
            if ident is not None:
                symbols.append((txt(ident),
                                "prototype" if is_proto else "variable",
                                txt(n).replace("\n", " ").strip()[:120],
                                line, n.end_point[0] + 1, "tree-sitter"))
        elif n.type == "preproc_include":
            p = n.child_by_field_name("path")
            if p is not None:
                edges.append((None, txt(p).strip('"<>'), None, "includes",
                              "tree-sitter", "confirmed"))
        elif n.type == "call_expression":
            fn = n.child_by_field_name("function")
            if fn is not None and fn.type in _TS_NAME_NODES:
                edges.append((enclosing, txt(fn), None, "calls",
                              "tree-sitter", "inferred"))
        elif n.type == "initializer_list":
            # 함수 포인터 테이블 — 초기화 리스트 안의 맨 식별자는 함수를
            # 가리킬 수 있다. 호출로 안 잡히므로 구멍으로 남긴다.
            for ch in n.children:
                if ch.type == "identifier":
                    gaps.append(("fnptr_table", ch.start_point[0] + 1,
                                 "%s — 테이블 등록. 호출로 잡히지 않음" % txt(ch),
                                 None, None))
        elif n.type == "preproc_arg":
            if "##" in txt(n):
                gaps.append(("token_paste", line,
                             "## 토큰 붙이기 — 생성되는 이름이 소스에 없음", None,
                             ",".join(_culprit_macros(text_lines,
                                                      n.start_point[0]))))
        elif n.type in ("preproc_ifdef", "preproc_if"):
            # preproc_else/elif 는 기록하지 않는다 — 머리 노드 하나가
            # 조건부 그룹 전체를 대표한다. 안 그러면 한 그룹이 2~3번 세어진다.
            if _ts_is_include_guard(n, src):
                gnm = n.child_by_field_name("name")
                if gnm is not None:
                    guard_names.add(txt(gnm))
            else:
                cond = n.child_by_field_name("name")
                gaps.append(("ifdef_branch", line,
                             "조건부 컴파일 %s — 어느 분기가 빌드되는지 알 수 없음"
                             % (txt(cond) if cond is not None else n.type),
                             None, None))
        elif n.type in ("gnu_asm_expression", "asm_statement"):
            gaps.append(("inline_asm", line, "인라인 asm — 해석 불가",
                         None, None))

        child_in_func = in_func or n.type == "function_definition"
        for ch in n.children:
            walk(ch, cur, child_in_func)

    walk(tree.root_node, None, False)
    return symbols, edges, gaps


_LAST_GAPS = []   # 직전 parse_file 호출이 발견한 구멍. cmd_index 가 회수한다.


def parse_file(path: Path, lang: str, text: str, ignore_macros=()):
    """(symbols, edges) 반환. 구멍은 _LAST_GAPS 에 남긴다.

    반환 시그니처를 바꾸지 않는 이유: cmd_doctor 등 기존 호출부를 깨지 않기 위함.
    ignore_macros 도 같은 이유로 선택 인자다 (기본값 = 기존 동작).
    """
    global _LAST_GAPS
    _LAST_GAPS = []
    if lang == "python":
        return parse_python(path, text)
    if lang in ("c", "cpp"):
        text = blank_macros(text, ignore_macros)
        r = parse_c_cpp_ts(path, text, lang)
        # `.h` 는 C 일 수도 C++ 일 수도 있다. 확장자만 믿으면 C++ 헤더를
        # C 문법으로 읽어 오류가 쏟아진다(실측: 사내 코드 .h 1,356개가 C++).
        # C 로 읽어 오류가 났을 때만 C++ 로 다시 읽고, 더 나은 쪽을 택한다.
        # `.c` 는 재시도하지 않는다 — 거기까지 추측하면 진짜 C 오류를 숨긴다.
        if (r is not None and lang == "c"
                and path.suffix.lower() in (".h", ".hxx", ".hh")):
            n_err = sum(1 for g in r[2]
                        if g[0] in ("parse_error", "parse_missing"))
            if n_err:
                alt = parse_c_cpp_ts(path, text, "cpp")
                if alt is not None:
                    alt_err = sum(1 for g in alt[2]
                                  if g[0] in ("parse_error", "parse_missing"))
                    if alt_err < n_err:
                        r = alt
        if r is not None:
            symbols, edges, gaps = r
            _LAST_GAPS = gaps
            return symbols, edges
        if has_universal_ctags():          # tree-sitter 없을 때만 폴백
            r2 = parse_c_cpp_ctags(path, text)
            if r2 is not None:
                return r2
        return parse_c_cpp(path, text)
    if lang == "idl":
        return parse_idl(path, text)
    return [], []

# ---------------------------------------------------------------- index

def resolve_include(dst_name, files_by_name):
    """include/import 대상을 저장소 내 파일로 해석 시도. 실패 = 외부 의존."""
    base = os.path.basename(dst_name)
    cands = files_by_name.get(base, [])
    if len(cands) == 1:
        return cands[0]
    for c in cands:  # 경로 끝부분이 일치하면 채택
        if c.endswith(dst_name):
            return c
    return None


def cmd_index(root: Path, only_files=None):
    cfg = load_config(root)
    con = open_db(root, create=True)
    con.executescript(SCHEMA)
    cur = con.cursor()

    all_paths = [p for p in iter_source_files(root, cfg)]
    files_by_name = {}
    for p in all_paths:
        rel = p.relative_to(root).as_posix()
        files_by_name.setdefault(p.name, []).append(rel)

    targets = all_paths
    if only_files is not None:
        wanted = set(only_files)
        targets = [p for p in all_paths
                   if p.relative_to(root).as_posix() in wanted]
        # 삭제된 파일 정리
        for f in only_files:
            if not (root / f).exists():
                cur.execute("DELETE FROM symbols WHERE file_id IN "
                            "(SELECT id FROM files WHERE path=?)", (f,))
                cur.execute("DELETE FROM edges WHERE src_file=?", (f,))
                cur.execute("DELETE FROM gaps WHERE file=?", (f,))
                cur.execute("DELETE FROM files WHERE path=?", (f,))
    else:
        cur.execute("DELETE FROM files")
        cur.execute("DELETE FROM symbols")
        cur.execute("DELETE FROM edges")
        cur.execute("DELETE FROM gaps")

    n_sym = n_edge = n_gap = 0
    show_progress = sys.stderr.isatty() and len(targets) > 10
    for i, p in enumerate(targets, 1):
        rel = p.relative_to(root).as_posix()
        if show_progress and (i % 10 == 0 or i == len(targets)):
            print(f"\r색인 중... {i}/{len(targets)}  {rel[:60]:<60}",
                  end="", file=sys.stderr, flush=True)
        try:
            raw, text, _enc = read_source(p)
        except Exception:
            continue
        lang = LANG_BY_EXT[p.suffix.lower()]
        sha = sha_of(raw)
        loc = text.count("\n") + 1
        cur.execute("DELETE FROM symbols WHERE file_id IN "
                    "(SELECT id FROM files WHERE path=?)", (rel,))
        cur.execute("DELETE FROM edges WHERE src_file=?", (rel,))
        cur.execute("DELETE FROM gaps WHERE file=?", (rel,))
        cur.execute("DELETE FROM files WHERE path=?", (rel,))
        cur.execute("INSERT INTO files(path, sha, lang, loc) VALUES(?,?,?,?)",
                    (rel, sha, lang, loc))
        fid = cur.lastrowid
        symbols, edges = parse_file(p, lang, text,
                                    cfg.get("ignore_macros", []))
        for (name, kind, sig, ls, le, prov) in symbols:
            cur.execute("INSERT INTO symbols(file_id,name,kind,signature,"
                        "line_start,line_end,provenance) VALUES(?,?,?,?,?,?,?)",
                        (fid, name, kind, sig, ls, le, prov))
            n_sym += 1
        for (src_sym, dst_name, _dst_file, kind, prov, conf) in edges:
            dst_file = None
            if kind in ("includes", "imports"):
                probe = dst_name.replace(".", "/") + ".py" \
                    if kind == "imports" else dst_name
                dst_file = resolve_include(probe, files_by_name)
            cur.execute("INSERT INTO edges(src_file,src_symbol,dst_name,"
                        "dst_file,kind,provenance,confidence) "
                        "VALUES(?,?,?,?,?,?,?)",
                        (rel, src_sym, dst_name, dst_file, kind, prov, conf))
            n_edge += 1
        # 미해석 대장 — 파서가 못 읽은 지점. 설계 §6.3
        for (gkind, gline, gdetail, gaffects, gevid) in _LAST_GAPS:
            cur.execute("INSERT INTO gaps(file,line,kind,detail,affects_symbol,"
                        "status,evidence) VALUES(?,?,?,?,?,'open',?)",
                        (rel, gline, gkind, gdetail, gaffects, gevid or None))
            n_gap += 1
    if show_progress:
        print(file=sys.stderr)
    n_bind = _link_boundaries(root, cur)
    con.commit()

    head = run_git(root, "rev-parse", "--short", "HEAD")
    state_p = root / ".codewiki" / "state.json"
    state = {}
    if state_p.exists():
        state = json.loads(state_p.read_text(encoding="utf-8"))
    state["last_indexed_commit"] = head
    state_p.write_text(json.dumps(state, indent=2), encoding="utf-8")

    scope = f"{len(targets)}개 파일(부분)" if only_files else f"{len(targets)}개 파일(전체)"
    if n_bind:
        scope += f", 경계 연결 {n_bind}개"
    print(f"색인 완료: {scope}, 심볼 {n_sym}개, 관계 {n_edge}개, 구멍 {n_gap}곳"
          f"{' [tree-sitter]' if ts_status()[0] else (' [ctags]' if has_universal_ctags() else ' [내장 스캐너]')}")
    if head:
        print(f"기준 커밋: {head}")

def _link_boundaries(root: Path, cur):
    """언어 경계 연결(미들웨어 중립). IDL/Franca 정의 파일과 코드 파일을
    (a) 파일 이름 줄기(rtiddsgen 등 생성 코드는 원본 이름을 물려받는 관례),
    (b) 인터페이스 이름 언급으로 잇는다. 전부 추정(inferred) 등급.
    RTI DDS / CycloneDDS / zenoh-pico / SOME-IP(Franca) 공통으로 동작."""
    idl_rows = cur.execute("SELECT path FROM files WHERE lang='idl'").fetchall()
    if not idl_rows:
        return 0
    cur.execute("DELETE FROM edges WHERE kind IN ('binds','generated_from')")
    stems = {Path(ip).stem: ip for (ip,) in idl_rows if len(Path(ip).stem) >= 4}
    names = {}
    for name, ipath in cur.execute(
            "SELECT s.name, f.path FROM symbols s JOIN files f ON f.id=s.file_id "
            "WHERE f.lang='idl' AND s.kind IN "
            "('idl_interface','idl_struct','idl_module') AND length(s.name)>=4"):
        names.setdefault(name, set()).add(ipath)
    # 프로젝트 내에서 유일하게 정의된 이름만 사용 (동명이인 방지)
    names = {n: ps.pop() for n, ps in names.items()
             if len(ps) == 1 and n not in CALL_NOISE}
    name_rx = None
    if names:
        alt = "|".join(re.escape(n) for n in
                       sorted(names, key=len, reverse=True))
        name_rx = re.compile(rf"\b({alt})\b")
    n_edges = 0
    for (path, lang) in cur.execute(
            "SELECT path, lang FROM files WHERE lang!='idl'").fetchall():
        base = Path(path).stem
        for stem, ipath in stems.items():
            if base == stem or base.startswith(stem):
                cur.execute(
                    "INSERT INTO edges(src_file,src_symbol,dst_name,dst_file,"
                    "kind,provenance,confidence) VALUES(?,?,?,?,?,?,?)",
                    (path, None, stem, ipath, "generated_from",
                     "stem-match", "inferred"))
                n_edges += 1
        if name_rx is None:
            continue
        try:
            text = read_source(root / path)[1]
        except Exception:
            continue
        hit_names = {m.group(1) for m in name_rx.finditer(text)}
        for n in sorted(hit_names):
            cur.execute(
                "INSERT INTO edges(src_file,src_symbol,dst_name,dst_file,"
                "kind,provenance,confidence) VALUES(?,?,?,?,?,?,?)",
                (path, None, n, names[n], "binds", "name-match", "inferred"))
            n_edges += 1
    return n_edges


# ---------------------------------------------------------------- stubs

STUB_HEADER = """---
type: file-stub
generated: true
source: {src}
source_sha: {sha}
lang: {lang}
---
> ⚙️ **자동 생성 문서 — 편집 금지.** `cw.py stubs` 실행 시 통째로 덮어써집니다.
> 원본: `{src}` ({loc}줄)

"""


# stub 하나에 적을 심볼 표의 최대 행 수. 칩 레지스터 헤더는 매크로가
# 수천 개라 전부 적으면 파일 하나가 수백 KB가 된다.
STUB_SYMBOL_LIMIT = 80


def stub_rel(src_rel: str) -> str:
    return f"files/{src_rel}.md"


def cmd_stubs(root: Path):
    con = open_db(root)
    cur = con.cursor()
    wiki = root / "wiki"
    files_dir = wiki / "files"
    if files_dir.exists():
        shutil.rmtree(files_dir)
    files = cur.execute("SELECT id, path, sha, lang, loc FROM files "
                        "ORDER BY path").fetchall()
    known = {f[1] for f in files}
    show_progress = sys.stderr.isatty() and len(files) > 10
    for i, (fid, path, sha, lang, loc) in enumerate(files, 1):
        if show_progress and (i % 20 == 0 or i == len(files)):
            print(f"\rstub 생성 중... {i}/{len(files)}",
                  end="", file=sys.stderr, flush=True)
        out = wiki / stub_rel(path)
        out.parent.mkdir(parents=True, exist_ok=True)
        body = [STUB_HEADER.format(src=path, sha=sha, lang=lang, loc=loc)]
        syms = cur.execute(
            "SELECT name, kind, signature, line_start FROM symbols "
            "WHERE file_id=? ORDER BY line_start", (fid,)).fetchall()
        if syms:
            from collections import Counter
            by_kind = Counter(k for _n, k, _s, _l in syms)
            summary = ", ".join(f"{k} {v}" for k, v in by_kind.most_common())
            body.append(f"## 심볼 (기계 추출)\n\n총 {len(syms)}개 — {summary}\n\n")
            # 칩 레지스터 헤더처럼 매크로가 수천 개인 파일이 있다. 전부 적으면
            # stub 하나가 수백 KB가 되어 아무도 못 읽고 위키가 비대해진다.
            # 상한을 두되, 몇 개를 생략했는지는 반드시 밝힌다.
            shown = syms[:STUB_SYMBOL_LIMIT]
            body.append("| 이름 | 종류 | 위치 | 시그니처 |\n|---|---|---|---|\n")
            for name, kind, sig, ls in shown:
                sig = (sig or "").replace("|", "\\|")
                body.append(f"| `{name}` | {kind} | {path}:{ls} | `{sig}` |\n")
            if len(syms) > len(shown):
                body.append(
                    f"\n> 위 표는 앞의 {len(shown)}개만 보여줍니다. "
                    f"**{len(syms) - len(shown)}개 생략됨.**\n"
                    f"> 생략된 것도 색인에는 다 들어 있습니다 — "
                    f"`cw context <이름>` 으로 조회하세요.\n")
            body.append("\n")
        deps = cur.execute(
            "SELECT dst_name, dst_file, kind FROM edges WHERE src_file=? "
            "AND kind IN ('includes','imports') ORDER BY dst_name",
            (path,)).fetchall()
        if deps:
            body.append("## 의존 (include/import — 기계 추출)\n\n")
            for dst_name, dst_file, kind in deps:
                if dst_file and dst_file in known:
                    body.append(f"- [[{stub_rel(dst_file)[:-3]}|{dst_name}]]\n")
                else:
                    body.append(f"- `{dst_name}` (외부 또는 미해석)\n")
            body.append("\n")
        bounds = cur.execute(
            "SELECT src_file, dst_name, dst_file, kind FROM edges "
            "WHERE (src_file=? OR dst_file=?) AND kind IN "
            "('binds','generated_from') ORDER BY kind, src_file",
            (path, path)).fetchall()
        if bounds:
            body.append("## 언어 경계 연결 (이름 기반 추정)\n\n")
            for src, dname, dfile, kind in bounds[:20]:
                if src == path and kind == "generated_from":
                    body.append(f"- [[{stub_rel(dfile)[:-3]}|{dfile}]] 에서 "
                                f"생성된 코드로 보임\n")
                elif src == path:
                    body.append(f"- `{dname}` ([[{stub_rel(dfile)[:-3]}|{dfile}]]"
                                f") 을 참조하는 것으로 보임\n")
                else:
                    body.append(f"- [[{stub_rel(src)[:-3]}|{src}]] 가 이 파일의 "
                                f"`{dname}` 를 참조하는 것으로 보임\n")
            body.append("\n")
        body.append("## 참고\n\n- 이 목록에 없는 관계(동적 호출, 함수 포인터, "
                    "DI 등)는 '없는 것'이 아니라 '기계가 확인 못 한 것'입니다.\n")
        out.write_text("".join(body), encoding="utf-8")
    if show_progress:
        print(file=sys.stderr)
    _write_index(root, cur)
    _write_module_map(root, cur)
    print(f"stub 생성 완료: wiki/files/ 아래 {len(files)}개 + INDEX.md "
          f"+ module-map.md")


def _module_depth(paths):
    """최상위 폴더가 3개 이하면(모든 코드가 src/ 밑 등) 한 단계 더 세분화."""
    tops = {p.split("/")[0] for p in paths if "/" in p}
    return 2 if len(tops) <= 3 else 1


def _module_of(path, depth):
    parts = path.split("/")
    if len(parts) > depth:
        return "/".join(parts[:depth])
    return "/".join(parts[:-1]) or "(root)"


def _write_module_map(root: Path, cur):
    """모듈(폴더) 사이 의존 그래프를 mermaid로 자동 생성 — 낡지 않는 조감도."""
    paths = [r[0] for r in cur.execute("SELECT path FROM files")]
    if not paths:
        return
    depth = _module_depth(paths)
    agg = {}
    for src, dst, kind in cur.execute(
            "SELECT src_file, dst_file, kind FROM edges "
            "WHERE dst_file IS NOT NULL AND kind IN "
            "('includes','imports','binds','generated_from')"):
        ms, md = _module_of(src, depth), _module_of(dst, depth)
        if ms == md:
            continue
        boundary = kind in ("binds", "generated_from")
        agg[(ms, md, boundary)] = agg.get((ms, md, boundary), 0) + 1

    def nid(m):
        return re.sub(r"\W", "_", m)

    lines = ["---\ntype: module-map\ngenerated: true\n---\n",
             "> ⚙️ 자동 생성 — 편집 금지. `cw.py stubs` 때마다 다시 그려집니다.\n\n",
             "# 모듈 관계 지도\n\n",
             "화살표 = 참조 방향(A→B: A가 B를 사용). 숫자 = 참조 건수. "
             "실선 = include/import, 점선 = 언어 경계(추정).\n\n",
             "```mermaid\nflowchart LR\n"]
    mods = sorted({m for (a, b, _) in agg for m in (a, b)})
    for m in mods:
        lines.append(f'    {nid(m)}["{m}"]\n')
    for (a, b, boundary), c in sorted(agg.items(), key=lambda x: -x[1])[:60]:
        arrow = "-.->" if boundary else "-->"
        lines.append(f'    {nid(a)} {arrow}|{c}| {nid(b)}\n')
    lines.append("```\n")
    if not agg:
        lines.append("\n(모듈 사이 참조가 아직 색인되지 않았습니다.)\n")
    (root / "wiki" / "module-map.md").write_text("".join(lines),
                                                 encoding="utf-8")


def _fan_in(cur):
    return cur.execute(
        "SELECT dst_file, COUNT(*) c FROM edges WHERE dst_file IS NOT NULL "
        "GROUP BY dst_file ORDER BY c DESC LIMIT 15").fetchall()


def _write_index(root: Path, cur):
    lines = ["---\ntype: file-index\ngenerated: true\n---\n",
             "> ⚙️ 자동 생성 — 편집 금지.\n\n# 파일 색인\n\n"]
    lines.append("## 많이 참조되는 파일 (fan-in 상위)\n\n"
                 "다른 파일이 많이 include/import 하는 파일 = 변경 파급이 큰 파일.\n\n")
    for path, c in _fan_in(cur):
        lines.append(f"- [[{stub_rel(path)[:-3]}|{path}]] ← {c}개 파일이 참조\n")
    lines.append("\n## 디렉터리별\n\n")
    dirs = {}
    for (path, lang, loc) in cur.execute(
            "SELECT path, lang, loc FROM files ORDER BY path"):
        d = str(Path(path).parent)
        dirs.setdefault(d, []).append((path, lang, loc))
    for d in sorted(dirs):
        total = sum(x[2] for x in dirs[d])
        lines.append(f"\n### `{d}/` — {len(dirs[d])}개 파일, {total}줄\n\n")
        for path, lang, loc in dirs[d]:
            lines.append(f"- [[{stub_rel(path)[:-3]}|{Path(path).name}]] ({lang}, {loc}줄)\n")
    (root / "wiki" / "files" / "INDEX.md").write_text("".join(lines),
                                                      encoding="utf-8")

# ---------------------------------------------------------------- map

MAP_ENTRY_LIMIT = 40


# 그룹이 이보다 많아지면 더 쪼개지 않는다. 목록이 길면 통째로 무시당한다.
MODULE_GROUP_BUDGET = 60

# 목표 그룹 수. 기준값을 저장소 크기에 맞추는 데 쓴다.
MODULE_TARGET_GROUPS = 25


def _module_dirs(cur):
    """디렉터리를 모듈 후보로 묶는다. map 과 lint 가 **같은 목록**을 봐야 한다.

    목록이 서로 다르면 lint 는 "안 덮인 폴더가 있다"는데 map 에는 그게 없어서
    AI 가 무엇을 써야 할지 모르는 상태가 된다 — 영원히 안 끝난다.

    깊이를 고정하면 안 된다. 가지마다 깊이가 다르기 때문이다. 1칸/2칸 고정
    방식은 `src/modules/can/driver` 같은 트리를 `src/modules` 하나로 뭉갰다.
    CAN·네트워크·보안이 한 덩어리가 되어 목록이 쓸모없어졌다.

    그래서 **큰 것부터 쪼갠다**: 파일 수가 기준을 넘고 하위 폴더가 있으면
    한 단계 내려간다. 기준값은 저장소 크기를 따라간다 — 9,099 파일짜리에
    고정 기준을 쓰면 그룹이 수백 개가 되고, 12 파일짜리에 쓰면 1개가 된다.
    """
    rows = cur.execute("SELECT path, lang, loc FROM files").fetchall()
    if not rows:
        return {}
    target = max(MODULE_MIN_FILES, len(rows) // MODULE_TARGET_GROUPS)

    pending = [("", [(p.split("/"), lang, loc) for p, lang, loc in rows])]
    done = []
    while pending:
        pending.sort(key=lambda g: -len(g[1]))       # 큰 것부터
        name, items = pending.pop(0)
        children, own = {}, []
        for parts, lang, loc in items:
            if len(parts) > 1:
                children.setdefault(parts[0], []).append((parts[1:], lang, loc))
            else:
                own.append((parts, lang, loc))
        after = len(done) + len(pending) + len(children) + (1 if own else 0)
        if (len(items) <= target or not children
                or after > MODULE_GROUP_BUDGET):
            done.append((name, items))
            continue
        # 하위 폴더와 나란히 있는 직속 파일은 자기 그룹을 갖는다.
        # 안 그러면 어디에도 안 속해서 덮기 검사에서 샌다.
        if own:
            done.append((name, own))
        for child, sub in children.items():
            pending.append((f"{name}/{child}" if name else child, sub))

    dirs = {}
    for name, items in done:
        d = dirs.setdefault(name or "(root)",
                            {"files": 0, "loc": 0, "langs": set()})
        for _parts, lang, loc in items:
            d["files"] += 1
            d["loc"] += loc
            d["langs"].add(lang)
    return dirs


def module_candidates(cur):
    """[(디렉터리, 파일수, 줄수)] — 규모 큰 순. 문서화해야 할 대상 목록이다."""
    dirs = _module_dirs(cur)
    return [(name, dirs[name]["files"], dirs[name]["loc"])
            for name in sorted(dirs, key=lambda k: -dirs[k]["loc"])]


# 파일이 이보다 적은 폴더는 모듈 문서를 강제하지 않는다.
# 한두 개짜리 폴더까지 에러로 만들면 목록이 노이즈가 되어 통째로 무시당한다.
MODULE_MIN_FILES = 2


def cmd_map(root: Path):
    con = open_db(root)
    cur = con.cursor()
    out = ["# 프로젝트 지도 (AI에게 이 파일 또는 .codewiki/map.md를 주면 됨)\n",
           "\n## 디렉터리 = 모듈 후보\n\n"]
    dirs = _module_dirs(cur)
    todo = [n for n, f, _l in module_candidates(cur) if f >= MODULE_MIN_FILES]
    out.append(f"**아래 `[ ]` 표시된 {len(todo)}개 폴더가 빠짐없이 덮여야 한다.**\n\n"
               "폴더 수 = 모듈 수가 아니다. **몇 개의 모듈로 나눌지, 어느 깊이로\n"
               "쓸지는 네가(또는 사용자가) 정한다.** 의미가 맞으면 여러 폴더를\n"
               "한 모듈로 묶어라 — 그게 더 나은 경우가 많다.\n\n"
               "기계가 보는 것은 하나뿐이다: **빠진 폴더가 있는가.**\n"
               "묶었으면 그 문서의 `depends` 에 묶은 경로를 전부 적어야\n"
               "덮인 것으로 인식된다. 남으면 `cw lint` 가 에러로 잡는다.\n\n")
    for name in sorted(dirs, key=lambda k: -dirs[k]["loc"]):
        d = dirs[name]
        mark = "[ ] " if d["files"] >= MODULE_MIN_FILES else "     "
        out.append(f"- {mark}`{name}/` : {d['files']}개 파일, {d['loc']}줄, "
                   f"언어={','.join(sorted(d['langs']))}\n")
    out.append("\n## 변경 파급이 큰 파일 (fan-in 상위)\n\n")
    for path, c in _fan_in(cur):
        out.append(f"- {path}  ← {c}개 파일이 참조\n")
    called = cur.execute(
        "SELECT dst_name, COUNT(DISTINCT src_file) c FROM edges "
        "WHERE kind='calls' GROUP BY dst_name "
        "HAVING c >= 2 ORDER BY c DESC LIMIT 10").fetchall()
    if called:
        out.append("\n## 여러 파일에서 호출되는 함수 상위 (이름 기반 추정)\n\n")
        for name, c in called:
            out.append(f"- `{name}()`  ← {c}개 파일에서 호출\n")
    out.append("\n## 엔트리포인트 후보\n\n")
    entries = []
    rows = cur.execute(
        "SELECT f.path, s.name, s.line_start FROM symbols s "
        "JOIN files f ON f.id=s.file_id WHERE s.name='main' "
        "OR s.kind='idl_interface' ORDER BY f.path").fetchall()
    for path, name, ls in rows:
        entries.append(f"- {path}:{ls}  `{name}`\n")
    py_mains = cur.execute("SELECT path FROM files WHERE lang='python'").fetchall()
    for (path,) in py_mains:
        try:
            if "__main__" in read_source(root / path)[1]:
                entries.append(f"- {path}  `if __name__ == '__main__'`\n")
        except Exception:
            pass
    out.extend(entries[:MAP_ENTRY_LIMIT])
    if len(entries) > MAP_ENTRY_LIMIT:
        out.append(f"- ... 외 {len(entries) - MAP_ENTRY_LIMIT}개 "
                   f"(전체는 facts.db에서 조회 가능)\n")
    text = "".join(out)
    map_p = root / ".codewiki" / "map.md"
    map_p.write_text(text, encoding="utf-8")
    print(text)
    print(f"(같은 내용이 {map_p.relative_to(root)} 에 저장됨 — "
          f"복사 대신 이 파일을 AI에게 줘도 됨)", file=sys.stderr)

# ---------------------------------------------------------------- lint

# ---------------------------------------------------------------- 표기법
# 신뢰도는 본문에 배지로 노출하고, 긴 앵커는 이름표 각주로 접는다.
# 설계: docs/superpowers/specs/2026-07-27-confidence-notation-design.md

BADGES = {
    "✅": "confirmed",   # 코드에서 직접 확인. 앵커 필수
    "🔍": "inferred",    # 정황 추론. 추론의 근거 필수
    "📄": "sourced",     # 코드 밖에서 채굴(커밋·주석·사양서). 출처 필수
    "❓": "unknown",     # 확인 못 함. 각주 없음
    "⚠️": "caution",     # 함정·예외 (U+26A0 U+FE0F)
    "⚠": "caution",      # 변이 선택자 없는 형태도 받는다
}

# 긴 것부터 정렬해야 ⚠️(2코드포인트)가 ⚠(1코드포인트)보다 먼저 매칭된다.
# 반대로 두면 변이 선택자 U+FE0F 가 본문 앞에 남는다.
_BADGE_ALT = "|".join(sorted((re.escape(b) for b in BADGES),
                             key=len, reverse=True))
RE_CLAIM = re.compile(r'^\s*[-*]\s+(' + _BADGE_ALT + r')\s*(.*)$')
RE_FOOTREF = re.compile(r'\[\^([\w\-.]+)\]')
RE_FOOTDEF = re.compile(r'^\[\^([\w\-.]+)\]:[ \t]*(.+)$')

Claim = namedtuple("Claim", "line badge text refs")


def parse_claims(body: str):
    """배지가 붙은 주장 줄을 뽑는다. line 은 1부터."""
    out = []
    for i, line in enumerate(body.split("\n"), 1):
        m = RE_CLAIM.match(line)
        if not m:
            continue
        badge, rest = m.group(1), m.group(2)
        refs = RE_FOOTREF.findall(rest)
        text = RE_FOOTREF.sub("", rest).strip()
        out.append(Claim(i, BADGES[badge], text, refs))
    return out


def parse_footnotes(body: str):
    """각주 정의 수집. {라벨: 정의본문}. 줄 맨 앞에서 시작하는 것만."""
    out = {}
    for line in body.split("\n"):
        m = RE_FOOTDEF.match(line)
        if m:
            out[m.group(1)] = m.group(2).strip()
    return out


# 배지별로 각주가 필수인가. ⚠️(caution)는 선택.
_BADGE_NEEDS_EVIDENCE = {
    "confirmed": "코드 앵커",
    "inferred": "추론의 근거",
    "sourced": "출처(커밋·주석·사양서)",
}


def lint_notation(rel: str, body: str, root: Path, cur):
    """표기법 검사. (errors, warns) 반환."""
    errors, warns = [], []
    claims = parse_claims(body)
    notes = parse_footnotes(body)
    used = set()

    for c in claims:
        used.update(c.refs)
        need = _BADGE_NEEDS_EVIDENCE.get(c.badge)
        if need and not c.refs:
            badge_ch = next(k for k, v in BADGES.items() if v == c.badge)
            errors.append(
                f"{rel}:{c.line} {badge_ch} 주장에 {need}가 없음 — "
                f"각주를 달거나 ❓로 낮추세요: \"{c.text[:30]}\"")
        if c.badge == "unknown" and c.refs:
            warns.append(
                f"{rel}:{c.line} ❓인데 근거가 붙어 있음 — "
                f"라벨이 잘못됐을 수 있습니다")
        if len(c.refs) > 1:
            warns.append(
                f"{rel}:{c.line} 한 주장에 근거가 {len(c.refs)}개입니다. "
                f"문장을 쪼개세요 — 어느 근거가 어느 부분을 뒷받침하는지 "
                f"알 수 없습니다")
        for r in c.refs:
            if r not in notes:
                errors.append(f"{rel}:{c.line} 각주 [^{r}] 의 정의가 없음")

    for label in notes:
        if label not in used:
            warns.append(f"{rel} 쓰이지 않는 각주 정의 [^{label}] (고아)")

    # 각주 정의 안의 앵커가 실존하는지
    for label, definition in notes.items():
        for m in re.finditer(r'`([^`]+)`', definition):
            a = m.group(1)
            if not (RE_ANCHOR_SYM.match(a) or RE_ANCHOR_LINE.match(a)):
                continue
            ok, msg = check_anchor(root, cur, a)
            if ok is False:
                errors.append(f"{rel} 각주 [^{label}] — {msg}")
            elif ok is None:
                warns.append(f"{rel} 각주 [^{label}] — {msg}")

    return errors, warns


# 요약 콜아웃에 쓸 표시 순서와 이름
_SUMMARY_ORDER = [("confirmed", "✅", "확인"), ("inferred", "🔍", "추론"),
                  ("sourced", "📄", "출처"), ("unknown", "❓", "모름"),
                  ("caution", "⚠️", "주의")]
RE_SUMMARY = re.compile(r'^> \[!info\] .*$', re.M)


def summary_callout(body: str) -> str:
    """문서의 신뢰도 구성을 한 줄로. 주장이 없으면 빈 문자열."""
    from collections import Counter
    counts = Counter(c.badge for c in parse_claims(body))
    if not counts:
        return ""
    parts = [f"{ch}{name} {counts[grade]}"
             for grade, ch, name in _SUMMARY_ORDER if counts.get(grade)]
    return "> [!info] " + " · ".join(parts)


def apply_summary(text: str) -> str:
    """프론트매터 뒤에 요약 콜아웃을 삽입하거나 갱신한다. 멱등."""
    fm_end = 0
    if text.startswith("---"):
        e = text.find("\n---", 3)
        if e >= 0:
            fm_end = e + 4
            if text[fm_end:fm_end + 1] == "\n":
                fm_end += 1

    head, body = text[:fm_end], text[fm_end:]
    body = RE_SUMMARY.sub("", body).lstrip("\n")   # 기존 요약 제거
    line = summary_callout(body)
    if not line:
        return head + body
    # 프론트매터가 있으면 사이에 빈 줄을 둔다 (--- 바로 밑에 붙으면 빡빡하다)
    sep = "\n" if head else ""
    return head + sep + line + "\n\n" + body


RE_ANCHOR_LINE = re.compile(r'^(?P<path>[\w./+\-]+):(?P<l1>\d+)(?:-(?P<l2>\d+))?$')
# sym: 접두어는 선택적이다. '#'이 있으면 심볼 앵커이므로 접두어가 중복이다.
# 기존 문서 호환을 위해 sym: 형태도 계속 받는다.
RE_ANCHOR_SYM = re.compile(
    r'^(?:sym:)?(?P<path>[\w./+\-]+)#(?P<name>[\w:~]+)$')


def parse_frontmatter(text: str):
    if not text.startswith("---"):
        return {}, text
    end = text.find("\n---", 3)
    if end < 0:
        return {}, text
    fm = {}
    key = None
    for line in text[3:end].splitlines():
        if not line.strip():
            continue
        m = re.match(r'^(\w[\w_]*):\s*(.*)$', line)
        if m:
            key = m.group(1)
            val = m.group(2).strip()
            fm[key] = val if val else []
        elif line.strip().startswith("- ") and key is not None:
            if not isinstance(fm[key], list):
                fm[key] = [fm[key]] if fm[key] else []
            fm[key].append(line.strip()[2:].strip())
    return fm, text[end + 4:]


def check_anchor(root: Path, cur, anchor: str):
    """anchor 유효성 검사 → (ok, message)"""
    anchor = anchor.strip()
    m = RE_ANCHOR_SYM.match(anchor)
    if m:
        row = cur.execute(
            "SELECT s.id FROM symbols s JOIN files f ON f.id=s.file_id "
            "WHERE f.path=? AND s.name=?",
            (m.group("path"), m.group("name"))).fetchone()
        if not (root / m.group("path")).exists():
            return False, f"파일 없음: {m.group('path')}"
        if not row:
            return None, (f"심볼 미확인(DB에 없음 — 존재하지 않는다는 뜻은 아님): "
                          f"{anchor}")
        return True, ""
    m = RE_ANCHOR_LINE.match(anchor)
    if m:
        p = root / m.group("path")
        if not p.exists():
            return False, f"파일 없음: {m.group('path')}"
        loc_row = cur.execute("SELECT loc FROM files WHERE path=?",
                              (m.group("path"),)).fetchone()
        loc = loc_row[0] if loc_row else None
        l2 = int(m.group("l2") or m.group("l1"))
        if loc and l2 > loc:
            return False, f"라인 범위 초과({l2} > {loc}줄): {anchor}"
        return True, ""
    m = RE_ANCHOR_LINE.match(anchor.split("@")[0]) if "@" in anchor else None
    if m:
        return check_anchor(root, cur, anchor.split("@")[0])
    if anchor == "edges" or anchor.startswith("edge"):
        return True, ""  # facts DB 전체를 근거로 지목
    return False, f"anchor 문법 오류: {anchor}"


def wiki_docs(root: Path):
    wiki = root / "wiki"
    for p in sorted(wiki.rglob("*.md")):
        rel = p.relative_to(wiki)
        if rel.parts and rel.parts[0] == "files":
            continue  # 자동 생성 stub은 검사 제외
        if p.name.startswith("_"):
            continue  # _TEMPLATE 등 템플릿 제외
        if p.name in ("conventions.md", "glossary.md"):
            continue  # 규칙 문서의 예시/용어집은 라벨 검사 대상 아님
        yield p


def cmd_lint(root: Path):
    con = open_db(root)
    cur = con.cursor()
    errors, warns = [], []
    head = run_git(root, "rev-parse", "--short", "HEAD")
    diff_cache = {}
    covered_globs = []

    for doc in wiki_docs(root):
        rel = str(doc.relative_to(root))
        text = doc.read_text(encoding="utf-8", errors="replace")
        fm, body = parse_frontmatter(text)
        dtype = fm.get("type", "")

        # 1) 표기법 검사 (배지 + 각주)
        e, w = lint_notation(rel, body, root, cur)
        errors.extend(e)
        warns.extend(w)

        # 요약 콜아웃은 기계 소유 — 검사하지 않고 갱신한다
        new_text = apply_summary(text)
        if new_text != text:
            doc.write_text(new_text, encoding="utf-8")

        # 2) 프론트매터 필수 필드 (modules/flows/contracts/overview)
        if dtype in ("module", "flow", "contract", "overview", "note"):
            for field in ("validated_at", "depends"):
                if field not in fm or not fm[field]:
                    errors.append(f"{rel} 프론트매터에 {field}가 없음")

        # 3) 최신성(staleness) 검사 — git 기준
        va = fm.get("validated_at")
        deps = fm.get("depends", [])
        if isinstance(deps, str):
            deps = [deps]
        if dtype in ("module", "flow", "contract", "note"):
            covered_globs.extend(deps)
            # 덮기만 하고 내용이 없는 문서를 잡는다. '덮이지 않은 폴더' 검사가
            # 생기면서 `- ❓ 아직 안 씀` 한 줄로 에러만 지우는 길이 열렸다.
            # 에러가 아니라 경고인 이유: ✅ 를 강제하면 근거 없는 확신을
            # 지어내게 된다. 모르는 것을 ❓ 로 두는 선택 자체는 정당하다.
            if not [c for c in parse_claims(body)
                    if c.badge in ("confirmed", "inferred", "sourced")]:
                warns.append(f"{rel} 내용이 없습니다 — 확인(✅)·추론(🔍)·"
                             f"출처(📄) 주장이 하나도 없음")
        if head and va and isinstance(va, str) and va not in ("TBD", ""):
            if va not in diff_cache:
                out = run_git(root, "diff", "--name-only", f"{va}..HEAD")
                diff_cache[va] = out.splitlines() if out is not None else None
            changed = diff_cache[va]
            if changed is None:
                warns.append(f"{rel} validated_at={va} 커밋을 git에서 찾지 못함")
            else:
                hits = set()
                for ch in changed:
                    for dep in deps:
                        pat = dep[4:] + "*" if dep.startswith("sym:") else dep
                        if fnmatch.fnmatch(ch, pat) or ch == dep:
                            hits.add(ch)
                if hits:
                    errors.append(f"{rel} ⏰ STALE — validated_at={va} 이후 의존 "
                                  f"파일 변경됨: {', '.join(sorted(hits)[:5])}")

    # 4) 완성도 — 아직 아무 문서도 다루지 않는 모듈이 남아 있는가
    #
    # 계기: 모듈 12개짜리 코드베이스에서 AI가 2개만 쓰고 끝내버렸다.
    # 표기법이 아무리 깨끗해도 10개가 비어 있으면 그 위키는 실패작이다.
    # 설계 §2.2-①대로, '충분한가'를 AI가 판단하게 두지 않고 기계가 센다.
    missing = []
    for name, n_files, n_loc in module_candidates(cur):
        if n_files < MODULE_MIN_FILES:
            continue
        probe = f"{name}/x.c" if name != "(root)" else "x.c"
        # 경계를 지켜 비교한다. 단순 startswith 로 하면 `src/mod11` 을 쓴 것이
        # `src/mod1` 까지 다뤄진 걸로 세어, 빠진 모듈이 조용히 통과한다.
        # 완성도 검사가 완성도를 속이는 셈이라 가장 나쁜 종류의 버그다.
        if any(fnmatch.fnmatch(probe, g) or g == name
               or g.startswith(name + "/")
               for g in covered_globs):
            continue
        missing.append((name, n_files, n_loc))
    if missing:
        total = sum(1 for _n, f, _l in module_candidates(cur)
                    if f >= MODULE_MIN_FILES)
        errors.append(
            f"{len(missing)}개 폴더가 어느 문서에도 덮이지 않았습니다 "
            f"(전체 {total}개) — 위키가 아직 덜 쓰였습니다")
        for name, n_files, n_loc in missing:
            errors.append(f"  {name}/ ({n_files}개 파일, {n_loc}줄) "
                          f"를 덮는 문서가 없음")

    for e in errors:
        print("에러:", e)
    for w in warns:
        print("경고:", w)
    print(f"\nlint 결과: 에러 {len(errors)}건, 경고 {len(warns)}건"
          f" (문서 {len(list(wiki_docs(root)))}개 검사)")
    if missing:
        print("→ 위 폴더들을 덮어야 합니다. 몇 개의 모듈로 묶을지는 자유이고,")
        print("  깊이도 자유입니다. 다만 빠지는 폴더가 없어야 합니다.")
        print("  전체 목록: `cw map` 또는 .codewiki/map.md")
    return 1 if errors else 0

# ---------------------------------------------------------------- update

def cmd_update(root: Path, mark_done=False):
    state_p = root / ".codewiki" / "state.json"
    state = json.loads(state_p.read_text(encoding="utf-8")) \
        if state_p.exists() else {}
    head = run_git(root, "rev-parse", "--short", "HEAD")
    if head is None:
        die("git 저장소가 아닙니다. update는 git 기반입니다. "
            "(git init 후 커밋하면 사용 가능)")

    if mark_done:
        state["wiki_synced_commit"] = head
        state_p.write_text(json.dumps(state, indent=2), encoding="utf-8")
        print(f"완료 표시: 위키가 커밋 {head} 기준으로 동기화되었다고 기록했습니다.")
        return

    base = state.get("wiki_synced_commit") or state.get("last_indexed_commit")
    if not base:
        die("기준 커밋이 없습니다. 먼저 `cw.py index` 후 "
            "`cw.py update --mark-done`으로 기준점을 만드세요.")
    if base == head:
        print(f"변경 없음 (기준 커밋 {base} == HEAD). 위키는 최신입니다.")
        return

    out = run_git(root, "diff", "--name-only", f"{base}..HEAD")
    if out is None:
        die(f"git diff 실패: {base}..HEAD")
    changed = [c for c in out.splitlines()
               if Path(c).suffix.lower() in LANG_BY_EXT]
    print(f"기준 {base} → HEAD {head}: 소스 변경 {len(changed)}건")
    for c in changed:
        print(f"  변경: {c}")

    if changed:
        cmd_index(root, only_files=changed)
        cmd_stubs(root)

    # stale 문서 판정
    stale = []
    for doc in wiki_docs(root):
        text = doc.read_text(encoding="utf-8", errors="replace")
        fm, _ = parse_frontmatter(text)
        deps = fm.get("depends", [])
        if isinstance(deps, str):
            deps = [deps]
        hits = set()
        for ch in changed:
            for dep in deps:
                pat = dep[4:] + "*" if dep.startswith("sym:") else dep
                if fnmatch.fnmatch(ch, pat) or ch == dep:
                    hits.add(ch)
        if hits:
            stale.append((str(doc.relative_to(root)), sorted(hits)))

    print()
    if not stale:
        print("stale 문서 없음. `cw.py update --mark-done`으로 기준점을 올리세요.")
        return
    print(f"⏰ 갱신 필요한 문서 {len(stale)}개 — AI에게 prompts/2-update.md와 "
          f"함께 아래 목록을 주세요:\n")
    for doc, hits in stale:
        print(f"- {doc}")
        for h in hits[:5]:
            print(f"    ← {h} 변경됨")
    print(f"\nAI 갱신이 끝나면: cw.py lint → cw.py update --mark-done")

# ---------------------------------------------------------------- init/status

AGENT_NOTE_BEGIN = "<!-- codewiki:begin -->"
AGENT_NOTE_END = "<!-- codewiki:end -->"


def agent_note_block(root: Path) -> str:
    """CLAUDE.md / AGENTS.md 에 넣을 안내 블록.

    **빈칸을 남기지 않는다.** 전에는 `python3 <codewiki>/cw.py` 처럼 자리표시자를
    적어놔서, 새 세션마다 AI 가 cw.py 를 찾아 헤맸다. CLAUDE.md 는 세션이
    시작될 때 자동으로 읽히므로, 여기에 **그대로 실행되는 명령**을 적어두면
    탐색이 아예 필요 없다. 프로젝트 경로도 적어 되묻지 않게 한다.
    """
    cw_path = TOOLKIT_DIR / "cw.py"
    proj = root.resolve()
    return (
        f"{AGENT_NOTE_BEGIN}\n"
        "## 프로젝트 지식 위키 (AI 에이전트용 — codewiki)\n\n"
        "이 저장소에는 codewiki가 관리하는 지식층이 있다. 코드를 뒤지기 전에\n"
        "여기를 먼저 보라. 아래 명령은 그대로 복사해 실행하면 된다.\n\n"
        f"툴킷 경로는 이미 알고 있다. **찾지 마라.**\n\n"
        f"```bash\n"
        f"cw() {{ python3 {cw_path} \"$@\"; }}\n"
        f"```\n\n"
        f"(`CW=\"python3 ...\"` 형태는 zsh 에서 단어 분리가 안 돼 실패한다. "
        f"함수를 써라.)\n\n"
        f"이 프로젝트: `{proj}`\n"
        "아래는 프로젝트 루트에서 실행한다. 다른 위치라면 `.` 대신 위 경로를 쓴다.\n\n"
        "| 하려는 일 | 명령 |\n"
        "|---|---|\n"
        f"| 심볼의 정의·호출자·관련 문서 | `cw context . <심볼이름>` |\n"
        f"| 파서가 못 읽은 곳 확인 | `cw parse-report .` |\n"
        f"| 위키 검사 | `cw lint .` |\n"
        f"| 코드 변경 후 낡은 문서 찾기 | `cw update .` |\n\n"
        "읽을 것:\n\n"
        "- 전체 구조: `wiki/00-overview.md` → 상세: `wiki/modules/`, `wiki/flows/`\n"
        "- 왜·함정: `wiki/decisions/`, `wiki/notes/` (코드에 없는 지식)\n"
        "- 프로젝트 지도: `.codewiki/map.md`\n"
        "- 위키 수정 시 규칙: `wiki/conventions.md` (배지·각주 필수)\n\n"
        "색인에 없다 = \"확인 못 함\"이지 \"존재하지 않음\"이 아니다.\n"
        f"{AGENT_NOTE_END}\n"
    )


def merge_agent_note(old: str, block: str) -> str:
    """기존 파일에 블록을 끼워넣거나 갱신한다.

    기존 내용을 지우지 않는다 — 그 프로젝트의 규칙이 적혀 있을 수 있다.
    표시자로 감싸서 반복 실행해도 블록이 하나만 남게 한다.
    """
    if old is None:
        return block
    if AGENT_NOTE_BEGIN in old and AGENT_NOTE_END in old:
        head = old.split(AGENT_NOTE_BEGIN)[0]
        tail = old.split(AGENT_NOTE_END, 1)[1]
        return head + block.rstrip("\n") + tail
    sep = "" if old.endswith("\n\n") else ("\n" if old.endswith("\n") else "\n\n")
    return old + sep + block


def install_skills(dest: Path, src: Path = None):
    """skill/* 를 dest 로 복사한다. (새로 깖, 갱신됨, 그대로) 이름 목록 반환.

    내용이 같으면 건드리지 않는다. 매번 '갱신됨'이 뜨면 사용자가 그 줄을
    무시하게 되고, 정작 진짜 갱신됐을 때 못 알아챈다.
    """
    src = src or (TOOLKIT_DIR / "skill")
    new, updated, same = [], [], []
    if not src.is_dir():
        return new, updated, same          # 배포본에 skill/ 이 없어도 죽지 않는다
    for skill_dir in sorted(p for p in src.iterdir() if p.is_dir()):
        name = skill_dir.name
        changed = fresh = False
        for f in sorted(skill_dir.rglob("*")):
            if not f.is_file():
                continue
            target = dest / name / f.relative_to(skill_dir)
            body = f.read_bytes()
            if not target.exists():
                fresh = True
            elif target.read_bytes() != body:
                changed = True
            else:
                continue
            target.parent.mkdir(parents=True, exist_ok=True)
            target.write_bytes(body)
        if fresh:
            new.append(name)
        elif changed:
            updated.append(name)
        else:
            same.append(name)
    return new, updated, same


def cmd_install_skills(root: Path, quiet=False):
    """스킬을 프로젝트와 개인 홈 양쪽에 깐다.

    - 프로젝트 `.claude/skills/` : 저장소를 받은 사람은 아무것도 안 해도 된다
    - 개인 `~/.claude/skills/`   : 그 사람의 모든 프로젝트에서 동작한다

    홈 폴더는 프로젝트 밖이므로 무엇을 어디에 썼는지 반드시 출력한다.
    """
    targets = [("프로젝트", root / ".claude" / "skills"),
               ("개인", Path.home() / ".claude" / "skills")]
    lines, any_change = [], False
    for label, dest in targets:
        try:
            new, updated, same = install_skills(dest)
        except OSError as e:
            lines.append(f"- {label} {dest}: 설치 실패 ({e})")
            continue
        if not (new or updated or same):
            continue
        bits = []
        if new:
            bits.append("새로 깖: " + ", ".join(new))
        if updated:
            bits.append("갱신: " + ", ".join(updated))
        if same:
            bits.append("그대로: " + ", ".join(same))
        any_change = any_change or bool(new or updated)
        try:
            shown = dest.relative_to(root)
        except ValueError:
            shown = dest
        lines.append(f"- {label} {shown} — " + " / ".join(bits))

    if not lines:
        if not quiet:
            print("설치할 스킬이 없습니다 (배포본에 skill/ 폴더가 없습니다)")
        return 0
    if quiet and not any_change:
        return 0
    print("\nClaude Code 스킬")
    for line in lines:
        print(line)
    if any_change:
        print("  → Claude Code 를 다시 켜면 인식됩니다. "
              "이후 '위키 만들어줘' 한마디로 됩니다.")
    return 0


def cmd_init(root: Path, show_next=True):
    root = root.resolve()
    if not root.exists():
        die(f"경로가 없습니다: {root}")
    tpl = TOOLKIT_DIR / "templates" / "wiki"
    wiki = root / "wiki"
    if not tpl.exists():
        die(f"템플릿 폴더가 없습니다: {tpl}")
    wiki.mkdir(exist_ok=True)
    copied = []
    for src in tpl.rglob("*"):
        rel = src.relative_to(tpl)
        dst = wiki / rel
        if src.is_dir():
            dst.mkdir(parents=True, exist_ok=True)
        elif not dst.exists():  # 기존 문서는 절대 덮어쓰지 않음
            dst.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(src, dst)
            copied.append(str(rel))
    cw_dir = root / ".codewiki"
    cw_dir.mkdir(exist_ok=True)
    gi = cw_dir / ".gitignore"
    if not gi.exists():  # facts.db 등 도구 데이터가 커밋되지 않게
        gi.write_text("*\n", encoding="utf-8")
    cfg_p = cw_dir / "config.json"
    if not cfg_p.exists():
        cfg_p.write_text(json.dumps(
            {"exclude_dirs": DEFAULT_EXCLUDES,
             "ignore_macros": [],
             "_설명": "exclude_dirs: 색인에서 제외할 디렉터리 패턴 / "
                      "ignore_macros: 파싱 전에 지울 장식 매크로 이름 "
                      "(cw parse-report 가 무엇을 넣을지 알려준다)"},
            indent=2, ensure_ascii=False), encoding="utf-8")
    # 이 저장소에서 작업하는 AI 에이전트가 위키를 자동으로 알게 하는 안내 파일
    agent_note = agent_note_block(root)
    for fname in ("CLAUDE.md", "AGENTS.md"):
        p = root / fname
        old = p.read_text(encoding="utf-8", errors="replace") \
            if p.exists() else None
        new = merge_agent_note(old, agent_note)
        if new != old:
            p.write_text(new, encoding="utf-8")
            print(f"  {fname} {'갱신' if old else '생성'} "
                  f"(AI 에이전트용 위키 안내)")
    print(f"초기화 완료: {root}")
    print(f"  wiki/ 에 템플릿 {len(copied)}개 설치 (Obsidian에서 wiki/를 vault로 여세요)")
    if show_next:
        print(f"  다음: cw.py index {root} && cw.py stubs {root}")


def cmd_status(root: Path):
    p = db_path(root)
    if not p.exists():
        print("색인 없음 — `cw.py index` 를 먼저 실행하세요.")
        return
    con = open_db(root)
    cur = con.cursor()
    nf = cur.execute("SELECT COUNT(*), COALESCE(SUM(loc),0) FROM files").fetchone()
    ns = cur.execute("SELECT COUNT(*) FROM symbols").fetchone()[0]
    ne = cur.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
    state_p = root / ".codewiki" / "state.json"
    state = json.loads(state_p.read_text(encoding="utf-8")) \
        if state_p.exists() else {}
    print(f"파일 {nf[0]}개 / {nf[1]}줄, 심볼 {ns}개, 관계 {ne}개")
    print(f"마지막 색인 커밋: {state.get('last_indexed_commit')}")
    print(f"위키 동기화 커밋: {state.get('wiki_synced_commit', '(미기록)')}")
    ndocs = len(list(wiki_docs(root))) if (root / "wiki").exists() else 0
    print(f"위키 문서(스텁 제외): {ndocs}개")

# ---------------------------------------------------------------- coverage

def cmd_coverage(root: Path):
    """위키가 코드의 어디를 다루고 어디가 비었는지 — '다음에 뭘 문서화할지'를
    감이 아니라 데이터로 정하게 해준다."""
    con = open_db(root)
    cur = con.cursor()
    docs = []
    if (root / "wiki").exists():
        for doc in wiki_docs(root):
            fm, _ = parse_frontmatter(
                doc.read_text(encoding="utf-8", errors="replace"))
            if fm.get("type") in ("module", "flow", "note", "contract"):
                deps = fm.get("depends", [])
                if isinstance(deps, str):
                    deps = [deps]
                if deps:
                    docs.append((str(doc.relative_to(root)), deps))
    files = [r[0] for r in cur.execute("SELECT path FROM files")]
    covered = set()
    for f in files:
        for _dname, deps in docs:
            if any(fnmatch.fnmatch(f, d) for d in deps):
                covered.add(f)
                break
    total = len(files)
    pct = 100 * len(covered) // max(total, 1)
    print(f"# 위키 커버리지\n")
    print(f"전체: {len(covered)}/{total} 파일 ({pct}%) — "
          f"depends를 가진 문서 {len(docs)}개 기준\n")

    depth = _module_depth(files)
    mods = {}
    for f in files:
        m = _module_of(f, depth)
        tot, cov = mods.get(m, (0, 0))
        mods[m] = (tot + 1, cov + (1 if f in covered else 0))
    print("## 모듈별\n")
    for m in sorted(mods, key=lambda k: mods[k][1] / mods[k][0]):
        tot, cov = mods[m]
        bar = "■" * (10 * cov // tot) + "□" * (10 - 10 * cov // tot)
        print(f"- {bar} {m}/  {cov}/{tot}")

    fan = cur.execute(
        "SELECT dst_file, COUNT(*) c FROM edges WHERE dst_file IS NOT NULL "
        "GROUP BY dst_file ORDER BY c DESC").fetchall()
    gaps = [(p, c) for p, c in fan if p not in covered][:15]
    if gaps:
        print("\n## 문서가 없는 중요 파일 (참조 많은 순 — 다음 문서화 후보)\n")
        for p, c in gaps:
            print(f"- {p}  ← {c}개 파일이 참조하는데 다루는 문서 없음")
    if not docs:
        print("\n(depends를 가진 위키 문서가 아직 없습니다 — "
              "모듈/흐름 문서를 먼저 생성하세요.)")


# ---------------------------------------------------------------- context

def uncertainties(root: Path, cur, query: str, def_files):
    """'위키와 facts.db 만으로는 확신할 수 없는 것'을 규칙으로 판정한다.

    AI 의 느낌이 아니라 데이터로 판정하므로 약한 모델도 쓸 수 있고
    비용이 예측 가능해진다.
    """
    out = []
    base = query.split("::")[-1]

    rows = cur.execute(
        "SELECT f.path, s.line_start FROM symbols s JOIN files f "
        "ON f.id=s.file_id WHERE s.name=? OR s.name LIKE ? "
        "ORDER BY f.path", (base, f"%::{base}")).fetchall()
    if not rows:
        out.append(
            f"`{base}` 를 색인에서 찾지 못했습니다 — 위키에 없다면 "
            f"코드에서 직접 찾아야 합니다 (매크로/템플릿 가능성)")
    elif len(rows) > 1:
        where = "  ".join(f"{p}:{l}" for p, l in rows[:5])
        out.append(
            f"`{base}` 이 {len(rows)}곳에 정의되어 있습니다 — "
            f"어느 것인지 코드로 확인하세요\n     {where}")

    # 파싱 실패 계열만 본다. ifdef/fnptr 은 코드의 성질이지 '못 읽음'이 아니라
    # 여기 섞으면 거의 모든 파일이 걸려 목록이 노이즈가 된다.
    if def_files:
        ph = ",".join("?" * len(def_files))
        qh = ",".join("?" * len(PARSE_QUALITY_GAPS))
        for path, cnt in cur.execute(
                f"SELECT file, COUNT(*) FROM gaps WHERE file IN ({ph}) "
                f"AND kind IN ({qh}) GROUP BY file ORDER BY COUNT(*) DESC",
                list(def_files) + list(PARSE_QUALITY_GAPS)):
            out.append(
                f"{path} 에 못 읽은 곳이 {cnt}곳 있습니다 — "
                f"호출자·정의 목록이 불완전할 수 있습니다")

    # 위키의 추론 문장 — 사실로 전달하면 안 되므로 확인 대상이다
    if (root / "wiki").exists():
        for doc in wiki_docs(root):
            text = doc.read_text(encoding="utf-8", errors="replace")
            _fm, body = parse_frontmatter(text)
            if base not in body:
                continue
            for c in parse_claims(body):
                if c.badge == "inferred" and base in c.text:
                    out.append(
                        f"위키 문장 \"{c.text[:40]}\" 은 추론입니다 "
                        f"({doc.relative_to(root)}:{c.line}) — 확인 필요")
    return out


def cmd_context(root: Path, query: str):
    """심볼 이름(또는 파일 경로)에 대한 작업 컨텍스트를 조립해 출력.
    출력을 그대로 AI에게 주면 해당 심볼 작업에 필요한 지도가 된다."""
    con = open_db(root)
    cur = con.cursor()
    base = query.split("::")[-1]
    print(f"# 작업 컨텍스트: {query}\n")

    syms = cur.execute(
        "SELECT f.path, s.name, s.kind, s.signature, s.line_start, s.line_end "
        "FROM symbols s JOIN files f ON f.id=s.file_id "
        "WHERE s.name=? OR s.name=? OR s.name LIKE ? OR f.path=? "
        "ORDER BY f.path LIMIT 10",
        (query, base, f"%::{base}", query)).fetchall()
    def_files = sorted({r[0] for r in syms})
    if syms:
        print("## 정의 위치\n")
        for path, name, kind, sig, ls, le in syms:
            print(f"- `{name}` ({kind}) {path}:{ls}-{le}  `{sig}`")
    else:
        print(f"## 정의 위치\n\n- facts.db에서 찾지 못함 "
              f"(존재하지 않는다는 뜻은 아님 — 매크로/템플릿 가능성)")

    callers = cur.execute(
        "SELECT DISTINCT src_file, src_symbol FROM edges "
        "WHERE kind='calls' AND dst_name=? LIMIT 15", (base,)).fetchall()
    print("\n## 호출자 (이름 기반 추정 — 동명 함수 가능성 있음)\n")
    if callers:
        for src_file, src_sym in callers:
            print(f"- {src_file} 의 `{src_sym}()`")
    else:
        print("- 색인에서 찾지 못함 (동적 호출/매크로는 안 잡힘)")

    callees = cur.execute(
        "SELECT DISTINCT dst_name FROM edges WHERE kind='calls' "
        "AND (src_symbol=? OR src_symbol=?) LIMIT 20",
        (query, base)).fetchall()
    if callees:
        print("\n## 호출 대상 (본문에서 발견된 이름들)\n")
        resolved = []
        for (dn,) in callees:
            hits = cur.execute(
                "SELECT DISTINCT f.path FROM symbols s "
                "JOIN files f ON f.id=s.file_id WHERE s.name=? OR s.name "
                "LIKE ? LIMIT 2", (dn, f"%::{dn}")).fetchall()
            loc = hits[0][0] if len(hits) == 1 else \
                ("여러 곳" if len(hits) > 1 else "외부/미해석")
            resolved.append(f"- `{dn}()` → {loc}")
        print("\n".join(sorted(resolved)))

    print("\n## 관련 위키 문서\n")
    found_doc = False
    if (root / "wiki").exists():
        for doc in wiki_docs(root):
            text = doc.read_text(encoding="utf-8", errors="replace")
            fm, body = parse_frontmatter(text)
            deps = fm.get("depends", [])
            if isinstance(deps, str):
                deps = [deps]
            dep_hit = any(fnmatch.fnmatch(f, dep) for f in def_files
                          for dep in deps)
            mention = base in body
            if dep_hit or mention:
                why = "의존 범위" if dep_hit else "본문 언급"
                print(f"- {doc.relative_to(root)} ({why})")
                found_doc = True
    if not found_doc:
        print("- 없음 — 이 심볼을 다루는 위키 문서가 아직 없음")
    for f in def_files:
        print(f"\n파일 stub: wiki/{stub_rel(f)}")

    unc = uncertainties(root, cur, query, def_files)
    print("\n## ⚠ 코드를 직접 확인해야 할 것\n")
    if unc:
        for i, u in enumerate(unc, 1):
            print(f"{i}. {u}")
        print("\n→ 이 목록에 있는 것만 코드를 여세요. 목록에 없으면 열지 마세요.")
    else:
        print("- 없음 — 위키와 색인만으로 답할 수 있습니다")


# ---------------------------------------------------------------- log

# 결과 문구에 이것이 들어 있으면 "위키에 없어서 코드를 봐야 했다"로 센다.
LOG_MISS_MARK = "위키없음"


def cmd_log(root: Path, op=None, text=None, result=None, gaps_only=False):
    """기록장 append / 조회.

    'query 가 코드를 열었다 = 위키에 없었다'가 핵심 신호다.
    이것이 ingest 의 입력이 된다.
    """
    import datetime
    p = root / "wiki" / "log.md"

    if not p.exists():
        print(f"기록장이 없습니다: {p} — 먼저 `cw init`을 실행하세요")
        return 1

    if op is not None:
        day = datetime.date.today().isoformat()

        def esc(s):
            return (s or "").replace("|", "\\|").replace("\n", " ")

        with p.open("a", encoding="utf-8") as f:
            f.write(f"| {day} | {esc(op)} | {esc(text)} | {esc(result)} |\n")
        return 0

    rows = []
    for line in p.read_text(encoding="utf-8").split("\n"):
        if not line.startswith("|"):
            continue
        cells = [c.strip() for c in line.strip("|").split("|")]
        if len(cells) < 4 or cells[0] == "날짜":
            continue
        if set(cells[0]) <= set("- "):      # 표 구분선
            continue
        rows.append(cells)

    if gaps_only:
        from collections import Counter
        misses = Counter(r[2] for r in rows
                         if r[1] == "query" and LOG_MISS_MARK in r[3])
        if not misses:
            print("위키에 없어서 코드를 열어본 질문이 아직 없습니다.")
            return 0
        print("## 위키에 없어서 코드를 열어본 질문 (많이 물어본 순)\n")
        for i, (q, n) in enumerate(misses.most_common(20), 1):
            print(f"  {i}. {q}  ({n}회 질문됨)")
        print("\n→ 이것이 다음에 문서화할 후보입니다. `ingest` 에 넘기세요.")
        return 0

    if not rows:
        print("기록이 아직 없습니다.")
        return 0
    print(f"## 최근 기록 (전체 {len(rows)}건)\n")
    for r in rows[-20:]:
        print(f"  {r[0]}  {r[1]:6}  {r[2][:40]:42}  {r[3][:30]}")
    return 0


# ---------------------------------------------------------------- doctor

SELFTEST_CASES = [
    ("C++ 같은 줄 중괄호", "cpp",
     "void Server::start(int port) {\n}\n", ["Server::start"]),
    ("C 다음 줄 중괄호(Allman)", "c",
     "int foo(int x)\n{\n  return x;\n}\n", ["foo"]),
    ("C++ 여러 줄 시그니처", "cpp",
     "static int helper(int a,\n    int b)\n{\n  return a;\n}\n", ["helper"]),
    ("C++ 생성자 초기화 리스트", "cpp",
     "class W {\npublic:\n  W(int i) : id_(i) {}\n};\n", ["W"]),
    ("C++ 주석 속 가짜 함수 무시", "cpp",
     "// void fake() {\nint real() {\n}\n", ["real"]),
    ("Python 함수/클래스", "python",
     "class H:\n    def run(self):\n        pass\n\ndef util(x):\n    return x\n",
     ["run", "util"]),
    ("IDL interface/메서드", "idl",
     "module M {\n  interface Svc {\n    void ping();\n  };\n};\n", ["ping"]),
    ("C++ operator()", "cpp",
     "struct S { int operator()(int a) const { return a; } };\n",
     ["operator()"]),
    ("AUTOSAR 스타일 시그니처", "c",
     "FUNC(void, RTE_CODE) Rte_Write_Sig(VAR(uint8, AUTOMATIC) v)\n"
     "{\n  send(v);\n}\n", ["Rte_Write_Sig"]),
]


GAP_LABEL = {
    "parse_error": "문법 해석 실패",
    "parse_missing": "빠진 토큰(매크로 의심)",
    "macro_mangled_decl": "매크로가 시그니처를 가림",
    "token_paste": "## 토큰 붙이기(이름이 소스에 없음)",
    "fnptr_table": "함수 포인터 테이블 등록",
    "ifdef_branch": "조건부 컴파일 분기",
    "inline_asm": "인라인 asm",
}

GAP_ADVICE = {
    "parse_error": "매크로 전개기가 필요합니다. 아래 파일의 매크로부터 처리하면 크게 줄어듭니다.",
    "parse_missing": "매크로 전개기가 필요합니다.",
    "macro_mangled_decl": "이 심볼들의 이름은 실제와 다를 수 있습니다. 위키에서 사실로 단정하면 안 됩니다.",
    "token_paste": "생성되는 함수 이름이 소스에 없습니다. 매크로 전개기 없이는 찾을 수 없습니다.",
    "fnptr_table": "여기 등록된 함수들은 '호출자 없음'으로 보일 수 있습니다. 데드코드 판정 시 주의하세요.",
    "ifdef_branch": "빌드 변형별로 다른 코드가 살아납니다. 어느 변형이 출하되는지는 코드에 없습니다.",
    "inline_asm": "해석 불가 구간입니다. 수동 확인이 필요합니다.",
}

# 판정(좋음/보통/나쁨)에 반영되는 구멍 — "파서가 읽어내지 못했다"에 해당하는 것들.
# fnptr_table / ifdef_branch / inline_asm 은 파싱 실패가 아니라 코드의 성질이다.
# 이들은 따로 보고하되 판정 비율에는 넣지 않는다. 안 그러면 매크로가 멀쩡한
# 코드도 #ifdef 가 많다는 이유로 '나쁨'이 되어 판정이 쓸모없어진다.
PARSE_QUALITY_GAPS = ("parse_error", "parse_missing",
                      "macro_mangled_decl", "token_paste")


# 문법이 깨진 자리에서 추출기가 심볼 이름으로 잘못 집어내는 키워드들.
# 진짜 심볼 이름일 수 없으므로 '사라졌다'고 세면 안 된다.
NOT_A_SYMBOL_NAME = {
    "class", "struct", "enum", "union", "namespace", "template", "typedef",
    "public", "private", "protected", "static", "const", "inline", "extern",
    "void", "int", "char", "long", "short", "float", "double", "unsigned",
    "signed", "bool", "auto", "using", "operator", "return", "if", "else",
}


def try_macro(files, name, base_ignore=()):
    """매크로 하나를 실제로 지워보고 좋아지는지 나빠지는지 잰다.

    files: [(Path, lang, text), ...]

    겉모습으로는 구분할 수 없기 때문에 실측한다. 셋 다 그냥 대문자 단어다:

      MEDIA_PUBLIC void f(int);      지우면 → 구멍 사라짐        (장식)
      RTI_BOOL check_cert(int);      지우면 → **함수가 사라짐**  (타입)
      MOCK_METHOD(int, run, (int));  지우면 → 구멍이 더 늘어남   (인자 받는)

    판정 우선순위에서 '해로움'이 가장 세다. 다른 파일에서 아무리 이득이
    나도 심볼을 하나라도 잃으면 넣으면 안 된다 — 위키에서 함수가 조용히
    사라지는 것이 이 프로젝트가 가장 피하려는 일이다.
    """
    base = list(base_ignore)
    before_syms, after_syms = set(), set()
    gaps_before = gaps_after = 0
    for path, lang, text in files:
        s1, _e = parse_file(path, lang, text, base)
        g1 = [g for g in _LAST_GAPS if g[0] in PARSE_QUALITY_GAPS]
        s2, _e = parse_file(path, lang, text, base + [name])
        g2 = [g for g in _LAST_GAPS if g[0] in PARSE_QUALITY_GAPS]
        before_syms.update((path.as_posix(), x[0]) for x in s1)
        after_syms.update((path.as_posix(), x[0]) for x in s2)
        gaps_before += len(g1)
        gaps_after += len(g2)

    # 깨진 파싱은 `class`/`struct` 같은 키워드를 심볼 이름으로 뱉는다.
    # 매크로를 지워 그게 사라지는 것은 손해가 아니라 이득이다. 이걸 손실로
    # 세면 멀쩡한 장식 매크로가 '해로움'으로 잘못 막힌다.
    lost = sorted({n for _f, n in before_syms - after_syms
                   if n and n not in NOT_A_SYMBOL_NAME})
    if lost:
        verdict = "해로움"
    elif gaps_after > gaps_before:
        verdict = "역효과"
    elif gaps_after < gaps_before:
        verdict = "도움됨"
    else:
        verdict = "효과 없음"
    return {"name": name, "verdict": verdict, "lost_symbols": lost,
            "gaps_before": gaps_before, "gaps_after": gaps_after,
            "n_files": len(files)}


# 매크로 하나를 재려고 파일을 두 번씩 파싱한다. 사내 코드베이스는
# 9,099 파일이라 전부 재면 너무 오래 걸린다. 표본으로도 판정은 갈린다.
TRY_MACRO_FILE_CAP = 40


def _spread(seq, k):
    """seq 에서 최대 k개를 고르게 뽑는다.

    앞에서 k개만 자르면 한 디렉터리에 몰려 같은 모양만 보게 된다.
    표본이 한쪽으로 쏠리면 판정이 뒤집힌다.
    """
    if k <= 0:
        return []
    if len(seq) <= k:
        return list(seq)
    step = len(seq) / k
    return [seq[int(i * step)] for i in range(k)]


def cmd_try_macros(root: Path):
    """범인 후보를 하나씩 지워보고, 안전하게 도움이 되는 것만 골라준다.

    설계 §2.2-①: 사용자는 사내 출력을 반출할 수 없고 사내 AI는 판단력이
    약하다. 그러므로 '알아서 판단해'가 아니라 기계가 실측해 결론을 낸다.
    """
    from collections import Counter
    con = open_db(root)
    cur = con.cursor()
    cfg = load_config(root)
    base = cfg.get("ignore_macros", [])

    ph = ",".join("?" * len(PARSE_QUALITY_GAPS))
    rows = cur.execute(
        f"SELECT file, evidence FROM gaps WHERE kind IN ({ph}) "
        "AND evidence IS NOT NULL AND evidence != ''",
        PARSE_QUALITY_GAPS).fetchall()
    if not rows:
        print("판정할 후보가 없습니다. 먼저 `cw index` 를 실행하세요.")
        return 0

    counts, gap_files = Counter(), {}
    for f, ev in rows:
        for nm in [x for x in ev.split(",") if x and x not in base]:
            counts[nm] += 1
            gap_files.setdefault(nm, set()).add(f)

    candidates = [nm for nm, _c in counts.most_common(12)]
    print("## 후보 매크로를 하나씩 실제로 지워보는 중")
    print(f"- 후보 {len(counts)}개 중 많이 나온 순으로 "
          f"{len(candidates)}개를 잽니다")

    # 잴 파일을 고른다. 구멍이 기록된 파일만 재면 안 된다 — 설정은 **모든**
    # 파일에 적용되므로, 지금 멀쩡한 파일에서 나는 손해를 놓치게 된다.
    # (실측: RTI_BOOL 은 구멍 난 파일에서는 이득이지만, 구멍 없는 파일에서는
    #  반환 타입이 사라져 함수가 통째로 증발한다.)
    # 그래서 그 이름이 '들어 있는' 파일을 전부 훑어 표본을 만든다.
    word = {nm: re.compile(r"\b%s\b" % re.escape(nm)) for nm in candidates}
    has_name = {nm: [] for nm in candidates}
    for rel, lang in cur.execute(
            "SELECT path, lang FROM files WHERE lang IN ('c','cpp')"):
        p = root / rel
        if not p.exists():
            continue
        try:
            _raw, text, _enc = read_source(p)
        except Exception:
            continue
        for nm in candidates:
            if word[nm].search(text):
                has_name[nm].append((rel, lang))

    results = []
    for nm in candidates:
        found = has_name[nm]
        # 구멍 난 파일(이득이 보이는 곳)과 멀쩡한 파일(손해가 숨은 곳)을
        # 반씩 섞는다. 한쪽만 보면 판정이 뒤집힌다.
        gapped = [x for x in found if x[0] in gap_files.get(nm, ())]
        clean = [x for x in found if x[0] not in gap_files.get(nm, ())]
        half = TRY_MACRO_FILE_CAP // 2
        picked = (_spread(gapped, half) + _spread(clean, TRY_MACRO_FILE_CAP - half))
        payload = []
        for rel, lang in picked:
            try:
                _raw, text, _enc = read_source(root / rel)
            except Exception:
                continue
            payload.append((root / rel, lang, text))
        if payload:
            results.append(try_macro(payload, nm, base))

    good = [r for r in results if r["verdict"] == "도움됨"]
    bad = [r for r in results if r["verdict"] == "해로움"]
    other = [r for r in results if r["verdict"] in ("역효과", "효과 없음")]

    if good:
        print("\n## 넣어도 되는 것 (구멍이 줄고, 잃는 심볼이 없음)")
        for r in good:
            print(f"- {r['name']}: 구멍 {r['gaps_before']} → "
                  f"{r['gaps_after']}곳 (파일 {r['n_files']}개 기준)")
    if bad:
        print("\n## 넣으면 안 되는 것 — 심볼이 사라집니다")
        for r in bad:
            ex = ", ".join(r["lost_symbols"][:3])
            print(f"- {r['name']}: {len(r['lost_symbols'])}개 사라짐 (예: {ex})")
        print("  → 타입 이름으로 쓰이는 매크로입니다. 지우면 반환 타입이")
        print("    없어져서 파서가 함수인 줄 모르게 됩니다.")
    if other:
        print("\n## 넣어도 소용없는 것")
        for r in other:
            why = ("괄호가 남아 더 나빠짐" if r["verdict"] == "역효과"
                   else "달라지는 것 없음")
            print(f"- {r['name']}: {why}")
        print("  → 인자를 받는 매크로는 이름만 지워서는 해결되지 않습니다.")
        print("    이런 것은 구멍으로 남겨두는 게 맞습니다.")

    print("\n" + "-" * 60)
    if not good:
        print("지워서 도움이 되는 매크로가 없습니다.")
        print("남은 구멍은 매크로를 지우는 방식으로는 줄일 수 없습니다.")
        return 0

    print("## .codewiki/config.json 에 붙여넣으세요")
    print('  "ignore_macros": '
          + json.dumps(base + [r["name"] for r in good], ensure_ascii=False))
    print("\n→ 넣고 `cw index` 후 `cw parse-report` 로 얼마나 줄었는지 보세요.")
    print("→ 위 '넣어도 되는 것'은 실제로 지워보고 확인한 결과입니다. "
          "추측이 아닙니다.")
    return 0


def cmd_parse_report(root: Path):
    """파서가 이 코드베이스를 얼마나 읽어냈는지 '결론'을 낸다.

    설계 §2.2-①: 사용자가 사내 출력을 반출할 수 없으므로 판단을 도구에 내장한다.
    데이터가 아니라 판정·원인·권고를 낸다.
    """
    from collections import Counter
    con = open_db(root)
    cur = con.cursor()

    n_files = cur.execute("SELECT COUNT(*) FROM files").fetchone()[0]
    n_sym = cur.execute("SELECT COUNT(*) FROM symbols").fetchone()[0]
    n_gap = cur.execute("SELECT COUNT(*) FROM gaps").fetchone()[0]

    ok, reason = ts_status()
    print("## 파서")
    print(f"- {reason}")
    if not ok:
        print("  → 정밀 모드가 아닙니다. 내장 스캐너는 자기가 못 읽은 곳을 "
              "알지 못하므로,\n    아래 '구멍' 수치는 실제보다 훨씬 적게 나옵니다.")

    print(f"\n## 규모\n- 파일 {n_files}개, 심볼 {n_sym}개, 구멍 {n_gap}곳")
    if n_files == 0:
        print("\n색인된 파일이 없습니다. 먼저 `cw index`를 실행하세요.")
        return 1

    # 판정은 '파서가 못 읽은 것'만으로 낸다. 조건부 컴파일이나 함수 포인터
    # 테이블은 코드의 성질이지 파싱 실패가 아니다.
    ph = ",".join("?" * len(PARSE_QUALITY_GAPS))
    bad_files = cur.execute(
        f"SELECT COUNT(DISTINCT file) FROM gaps WHERE kind IN ({ph})",
        PARSE_QUALITY_GAPS).fetchone()[0]

    ratio = bad_files / n_files
    if ratio < 0.10:
        verdict, code = "좋음", 0
    elif ratio < 0.30:
        verdict, code = "보통", 1
    else:
        verdict, code = "나쁨", 1
    print(f"\n## 판정: {verdict} "
          f"(파서가 못 읽은 파일 {bad_files}/{n_files} = {ratio*100:.0f}%)")

    kinds = Counter(r[0] for r in cur.execute("SELECT kind FROM gaps"))
    if not kinds:
        print("\n해석하지 못한 지점이 없습니다. 파서가 이 코드를 잘 읽고 있습니다.")
        return code

    quality = [(k, c) for k, c in kinds.most_common() if k in PARSE_QUALITY_GAPS]
    info = [(k, c) for k, c in kinds.most_common() if k not in PARSE_QUALITY_GAPS]

    if quality:
        print("\n## 파서가 못 읽은 것 (판정에 반영됨)")
        for kind, cnt in quality:
            print(f"- {GAP_LABEL.get(kind, kind)} ({kind}): {cnt}곳")
    if info:
        print("\n## 코드의 성질 (판정에 반영 안 됨, 그러나 알아야 함)")
        for kind, cnt in info:
            print(f"- {GAP_LABEL.get(kind, kind)} ({kind}): {cnt}곳")

    # 어떤 매크로 때문에 못 읽었는지를 이름으로 지목한다.
    # "매크로 전개기가 필요합니다"만으로는 무엇을 처리할지 알 수 없다.
    culprit = Counter()
    n_with_evidence = 0
    for (ev,) in cur.execute(
            f"SELECT evidence FROM gaps WHERE kind IN ({ph}) "
            "AND evidence IS NOT NULL AND evidence != ''", PARSE_QUALITY_GAPS):
        names = [x for x in ev.split(",") if x]
        if names:
            n_with_evidence += 1
        for nm in names:
            culprit[nm] += 1
    if culprit:
        total_q = sum(c for _k, c in quality)
        print("\n## 못 읽게 만든 범인 (많은 순)")
        top = culprit.most_common(10)
        for nm, cnt in top:
            print(f"- {nm}: {cnt}곳")
        covered = sum(c for _n, c in top[:3])
        if total_q:
            print(f"\n→ 상위 3개({', '.join(n for n, _ in top[:3])})만 처리하면 "
                  f"약 {min(100, 100 * covered // max(total_q, 1))}%가 줄어듭니다.")
        print("→ 이 목록을 개발자에게 그대로 전달하면 다음 작업을 정할 수 있습니다.")

        # 지목만 하고 끝내면 사용자가 '그래서 뭘 하지'에서 막힌다.
        # 그렇다고 이 목록을 그대로 붙여넣게 하면 안 된다 — 실측 결과
        # 매크로 종류에 따라 결과가 정반대다. 타입 이름으로 쓰이는 매크로를
        # 지우면 함수가 통째로 사라진다. 겉모습으로는 구분되지 않으므로
        # 기계가 하나씩 지워보고 판정하는 명령으로 넘긴다.
        print("\n## 바로 해볼 것")
        print("  cw try-macros .")
        print("\n위 이름들을 하나씩 실제로 지워보고, 안전하게 도움이 되는 것만")
        print("골라서 설정에 붙여넣을 형태로 내줍니다.")
        print("→ 이 목록을 그대로 설정에 넣지 마세요. 타입 이름으로 쓰이는")
        print("  매크로가 섞여 있으면 위키에서 함수가 조용히 사라집니다.")

    print("\n## 다음에 할 일")
    for kind, _cnt in (quality + info)[:3]:
        print(f"→ {GAP_ADVICE.get(kind, '확인이 필요합니다.')}")

    rows = cur.execute(
        f"SELECT file, COUNT(*) c FROM gaps WHERE kind IN ({ph}) "
        "GROUP BY file ORDER BY c DESC LIMIT 5", PARSE_QUALITY_GAPS).fetchall()
    if rows:
        print("\n## 못 읽은 곳이 몰린 파일 상위 5")
        for f, c in rows:
            print(f"- {f}: {c}곳")
        print("  → 이 파일들의 매크로를 먼저 처리하면 가장 크게 개선됩니다.")

    print("\n" + "-" * 60)
    if code:
        print("구멍이 있는 것은 고장이 아닙니다. 빌드를 돌리지 않고 소스만 읽는 이상\n"
              "매크로·조건부 컴파일은 원래 완전히 해석할 수 없습니다.\n"
              "중요한 건 '못 읽은 곳을 알고 있다'는 것이고, 위 목록이 바로 그것입니다.\n"
              "위키를 만들 때 AI가 이 지점들을 사실로 단정하지 않게 됩니다.")
    else:
        print("파서가 이 코드를 잘 읽고 있습니다. 위키를 만들어도 좋습니다.")
    return code


def cmd_doctor(root: Path):
    import platform
    print(f"## 환경\n- Python {sys.version.split()[0]} / {platform.system()} "
          f"{platform.release()}")
    _ts_ok, _ts_reason = ts_status()
    print(f"- C/C++ 파서: {_ts_reason}")
    if not _ts_ok:
        print(f"- universal-ctags: {'있음' if has_universal_ctags() else '없음'} "
              "(tree-sitter 없을 때만 쓰임)")
    head = run_git(root, "rev-parse", "--short", "HEAD")
    print(f"- git: {'커밋 ' + head if head else '저장소 아님 → update/최신성 검사 사용 불가'}")

    print("\n## 파서 자가 테스트")
    fails = 0
    for desc, lang, code, want in SELFTEST_CASES:
        syms, _ = parse_file(Path("selftest"), lang, code)
        got = sorted(s[0] for s in syms
                     if s[1] in ("function", "idl_method"))
        ok = got == sorted(want)
        if not ok:
            fails += 1
        print(f"- {'O' if ok else 'X'} {desc}"
              + ("" if ok else f"  (기대 {want}, 실측 {got})"))

    cfg = load_config(root)
    files = list(iter_source_files(root, cfg))
    print(f"\n## 색인 대상 훑기\n- 대상 파일: {len(files)}개")
    if _LAST_SKIPPED_GENERATED:
        print(f"- 생성 코드·템플릿 {_LAST_SKIPPED_GENERATED}개 제외됨 "
              "(.pb.h, .in.c 등 — 사람이 문서화할 대상이 아님)")
        print("  → 포함하려면 .codewiki/config.json 의 exclude_files 를 비우세요")
    from collections import Counter
    langs = Counter(LANG_BY_EXT[p.suffix.lower()] for p in files)
    print(f"- 언어별: {dict(langs)}")
    dirs = Counter("/".join(p.relative_to(root).parts[:2][:-1]) or
                   p.relative_to(root).parts[0] for p in files)
    print("- 파일 많은 폴더 상위 8 (서드파티/생성 코드면 exclude_dirs에 추가 권장):")
    for d, c in dirs.most_common(8):
        print(f"    {d}/ : {c}개")
    non_utf8 = 0
    for p in files[:300]:
        try:
            _, _, enc = read_source(p)
            if enc != "utf-8":
                non_utf8 += 1
        except Exception:
            pass
    if non_utf8:
        print(f"- 인코딩: 표본 300개 중 {non_utf8}개가 UTF-8 아님 "
              f"→ CP949 폴백으로 자동 처리됨 (한글 주석 보존)")
    else:
        print("- 인코딩: 표본에서 문제 없음 (UTF-8)")

    print("\n다음: `cw index` 후 `cw parse-report` 로 파서가 이 코드를 "
          "얼마나 읽어냈는지 확인하세요.")
    print(f"\n{'문제 없음 — index를 진행하세요.' if fails == 0 else '파서 테스트 실패 — 이 출력과 함께 문의하세요.'}")
    sys.exit(1 if fails else 0)


# ---------------------------------------------------------------- main

def main():
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("command", choices=["setup", "init", "index", "stubs",
                                        "map", "lint", "update", "status",
                                        "doctor", "context", "coverage",
                                        "parse-report", "try-macros",
                                        "install-skills", "log"])
    ap.add_argument("path", nargs="?", default=".",
                    help="대상 프로젝트 루트 (기본: 현재 디렉터리)")
    ap.add_argument("query", nargs="?",
                    help="(context 전용) 심볼 이름 또는 파일 경로")
    ap.add_argument("--mark-done", action="store_true",
                    help="(update 전용) 위키 갱신 완료를 현재 커밋으로 기록")
    # log 는 기존 'cw <명령> <경로>' 규칙을 지키려고 플래그를 쓴다.
    # 위치 인자를 더 쓰면 path 가 'add' 로 잡혀 프로젝트 경로를 못 받는다.
    ap.add_argument("--add", metavar="연산",
                    help="(log 전용) 기록 추가 — query/ingest/lint")
    ap.add_argument("--text", help="(log --add 전용) 기록할 내용")
    ap.add_argument("--result", help="(log --add 전용) 결과 요약")
    ap.add_argument("--gaps", action="store_true",
                    help="(log 전용) 위키에 없어서 코드를 열어본 질문만")
    args = ap.parse_intermixed_args()
    root = Path(args.path).resolve()
    if args.command == "setup":
        cmd_init(root, show_next=False)
        cmd_install_skills(root, quiet=True)
        cmd_index(root)
        cmd_stubs(root)
        print("\n" + "=" * 60)
        cmd_map(root)
        print("=" * 60)
        print("\n준비 끝. 다음 두 가지를 하세요:")
        print("  1) cw parse-report")
        print("     ← 파서가 이 코드를 얼마나 읽어냈는지 먼저 확인하세요.")
        print("       못 읽은 곳이 어디인지 알아야 위키를 믿을 수 있습니다.")
        print("  2) .codewiki/map.md 파일 + prompts/1-generate.md 를 AI에게 주고")
        print("     위키 생성을 시키세요. (Claude Code면 '위키 만들어줘' 한마디면 됨)")
        print("  이후 코드가 바뀌면: cw.py update")
    elif args.command == "init":
        cmd_init(root)
    elif args.command == "index":
        cmd_index(root)
    elif args.command == "stubs":
        cmd_stubs(root)
    elif args.command == "map":
        cmd_map(root)
    elif args.command == "lint":
        sys.exit(cmd_lint(root))
    elif args.command == "update":
        cmd_update(root, mark_done=args.mark_done)
    elif args.command == "status":
        cmd_status(root)
    elif args.command == "doctor":
        cmd_doctor(root)
    elif args.command == "parse-report":
        sys.exit(cmd_parse_report(root))
    elif args.command == "try-macros":
        sys.exit(cmd_try_macros(root))
    elif args.command == "install-skills":
        sys.exit(cmd_install_skills(root))
    elif args.command == "log":
        sys.exit(cmd_log(root, op=args.add, text=args.text,
                         result=args.result, gaps_only=args.gaps))
    elif args.command == "coverage":
        cmd_coverage(root)
    elif args.command == "context":
        if args.query is None:
            # `cw.py context 심볼` 형태: path 자리에 온 것이 질의어
            if args.path != "." and not Path(args.path).is_dir():
                cmd_context(Path(".").resolve(), args.path)
            else:
                die("사용법: cw.py context [프로젝트경로] <심볼이름|파일경로>")
        else:
            cmd_context(root, args.query)


if __name__ == "__main__":
    main()