"""데이터셋·TagSet·정책 색인 갱신 (계획 2026-09-27 L6 §2.5 · D-L6-7 · 검토 F2·F9). **키.** `sha256(JCS([lock_sha, template_sha, text_mode, INDEX_EXTRACTOR, index_code_sha]))` — `lock_sha` = lock 파일 바이트 sha256 (없으면 null), `template_sha` = 정책 템플릿 바이트 sha256(없으면 null), `text_mode` = `optin.text_mode()`, `INDEX_EXTRACTOR` = `poc_bundle.index.row_tags.EXTRACTOR`, `index_code_sha` = **`poc_bundle` 패키지 전체**의 `*.py` (상대 경로, 길이, 바이트)를 경로순으로 이은 sha256. 색인 출력은 `index/` 밖 모듈(`keys`·`scoring.policy`·`scoring.ids`·`snapshot`·`lock_match`·`canonical` …) 에도 달려 있어 `index/*.py` 만 보면 그쪽 변경을 놓친다(리뷰 지적 3) — 넓게 잡아 PB 가 바뀌면 한 번 더 만드는 쪽을 택했다 (`poc_bundle.__version__` 은 고정값이라 코드 변화를 못 잡는다). 키 파일은 `///hook/index-key.json`. **판정(순서대로).** 1. lock 이 없으면(`load_existing_lock(layout) is None`) 세 명령 모두 건너뛴다 → `skipped:no_lock`(실패 아님, D-L6-11). click 예외 문구는 파싱하지 않는다 — CLI 를 부르기 **전에** 가른다. 레이아웃·lock 을 읽지 못하면(깨진 lock 등) 가르지 않고 CLI 를 불러 그쪽이 실패를 보고하게 둔다. 2. 정책 템플릿이 없으면 `tags`·`policy` 는 건너뛰고 `datasets` 만 — 결과 `written:datasets_only`. 3. 키가 같고 색인 루트의 그 case 디렉토리(돌 명령의 것 — `datasets/`, 템플릿이 있으면 `tagsets/`·`policies/` 도)가 모두 있으면 `unchanged`. 아니면 **옛 키를 먼저 지우고** 명령을 차례로 부른 뒤, 건너뛰지 않은 명령이 모두 성공했을 때만 새 키를 쓴다 (원자적 쓰기). 옛 키를 남겨 두면 명령이 중간에 실패했을 때(datasets 는 새 입력으로 다시 쓰고 옛 파일을 지웠는데 tags 가 실패) 입력이 옛 값으로 돌아오는 순간 `unchanged` 로 오판해 섞인 사이드카가 영영 남는다(리뷰 지적 1). 중간의 KeyboardInterrupt 도 같은 길로 막힌다. **남은 옛 출력 치우기(리뷰 지적 2).** 건너뛴 명령이 예전에 쓴 디렉토리는 hub 가 그대로 읽는다(`ES/src/hub/stages/tagsets.ts` `loadPolicies` — 없는 디렉토리는 빈 목록이다). 그래서 lock 이 없으면 `datasets/`·`tagsets/`·`policies/`(와 키 파일)를, 템플릿만 없으면 `tagsets/`·`policies/` 를 색인 루트의 그 case 아래에서 지운다 — lock·템플릿에서만 나오는 파생물이다. 번들 색인 (`bundles/`)은 건드리지 않는다. 지운 이름은 `IndexOutcome.removed` 와 stderr 한 줄로 알린다. 레이아웃·lock 을 못 읽어 세 명령을 모두 부르는 경우에는 지우지 않는다(없다고 확정하지 못했다). **호출.** `poc_bundle.index.cli.index_group.main([...], prog_name="poc-bundle index", standalone_mode=False)` — 아카이브 루트 (`--projects-dir target.projects_dir`)·색인 루트(`--index-root hub_index_root()`)·텍스트 모드(`--text`)를 **명시**한다. stdout· stderr 는 버퍼에 받는다(경로·건수뿐이라 훅 콘솔은 다리마다 한 줄이다). 다만 stderr 의 **`warning:` 줄은 버리지 않는다**(리뷰 지적 4) — `index datasets` 의 "같은 dataset_version 을 나눠 가진 lock 항목"(hub 는 그중 하나만 싣는다)·`index policy` 의 "관측 0 인 선언 태그" 같은 정합성 경고다. 명령 이름을 붙여 stderr 에 다시 내고 `IndexOutcome.warnings` 에 싣는다(번들 다리는 detail 에 건수만 둔다 — 상태 파일은 코드·건수만). 실패는 `failed:index_<명령>:<종료 코드>` 이고 사람용 이유는 click 오류 문구(경로·코드만 — `index/cli.py` 모듈 설명 "행 본문은 싣지 않는다")의 마지막 줄이다. 돌려주는 값: `unchanged` · `written` · `written:datasets_only` · `skipped:no_lock` · `failed:index_<명령>:`. `poc_bundle` 은 함수 안에서만 import 한다(D-L6-14). """ from __future__ import annotations import contextlib import hashlib import io import json import os from collections.abc import Sequence from dataclasses import dataclass from pathlib import Path from typing import Any import click from solar_eval.hub_hook import optin from solar_eval.hub_hook.types import ( HOOK_DIRNAME, INDEX_CMD_DATASETS, INDEX_CMD_POLICY, INDEX_CMD_TAGS, INDEX_FAILED_PREFIX, INDEX_KEY_FILENAME, INDEX_UNCHANGED, INDEX_WRITTEN, INDEX_WRITTEN_DATASETS_ONLY, NO_LOCK, STATUS_FAILED, STATUS_SKIPPED, Target, ) #: 색인 명령과 그 명령이 쓰는 색인 루트 아래 디렉토리(`/accounts///`). CMD_DATASETS, CMD_TAGS, CMD_POLICY = INDEX_CMD_DATASETS, INDEX_CMD_TAGS, INDEX_CMD_POLICY OUTPUT_DIRS = {CMD_DATASETS: "datasets", CMD_TAGS: "tagsets", CMD_POLICY: "policies"} PROG_NAME = "poc-bundle index" #: 키 파일 스키마 — 훅 내부 기록(사람·다른 도구가 읽지 않는다). INDEX_KEY_SCHEMA = "solar-eval-hook-index-key/v1" #: 색인 CLI stderr 에서 정합성 경고로 보는 줄 머리(`poc_bundle/index/cli.py` 의 `warning: …`). WARNING_PREFIX = "warning:" @dataclass(frozen=True) class IndexOutcome: """`refresh` 결과 — `code` 는 모듈 설명의 반환 어휘, `reason` 은 실패일 때만 사람용 한 줄. `warnings` 는 성공한 명령의 stderr `warning:` 줄(`index <명령>: ` 접두), `removed` 는 이번에 치운 옛 출력 디렉토리 이름. """ code: str reason: str | None = None warnings: tuple[str, ...] = () removed: tuple[str, ...] = () @property def failed(self) -> bool: return self.code.startswith(f"{STATUS_FAILED}:") @dataclass(frozen=True) class IndexCall: """색인 명령 한 번의 결과 — 종료 코드, 실패면 click 문구 마지막 줄, stderr 의 `warning:` 줄.""" exit_code: int reason: str | None = None warnings: tuple[str, ...] = () @dataclass(frozen=True) class _Plan: commands: tuple[str, ...] key: str | None parts: dict[str, Any] | None def refresh_case_indexes(target: Target) -> str: """case 하나의 색인을 키가 바뀌었을 때만 다시 만든다(D-L6-7). 반환 어휘는 모듈 설명.""" return refresh(target).code def refresh(target: Target) -> IndexOutcome: """`refresh_case_indexes` 와 같고 실패 이유(사람용 한 줄)를 함께 돌려준다.""" plan = _plan(target) root = _index_root() removed = _remove_stale_outputs(target, plan, root) if not plan.commands: # lock 이 없다 — 키도 이제 가리킬 색인이 없다(lock 이 돌아오면 디렉토리가 없어 다시 만든다) key_path(target).unlink(missing_ok=True) return _announce(target, IndexOutcome(f"{STATUS_SKIPPED}:{NO_LOCK}", removed=removed)) if plan.key is not None and _unchanged(target, plan, root): return _announce(target, IndexOutcome(INDEX_UNCHANGED, removed=removed)) # 옛 키를 먼저 지운다 — 명령이 중간에 실패하면 사이드카가 섞인 채 옛 키가 남아 `unchanged` 로 오판한다(리뷰 지적 1) key_path(target).unlink(missing_ok=True) from poc_bundle.index.case import index_lock_derived warnings: list[str] = [] for command, call in index_lock_derived( target.case_ref, root, repo_root=target.repo_root, commands=plan.commands, text_mode=optin.text_mode(), projects_dir=target.projects_dir, invoke=invoke_index, ): warnings += [f"index {command}: {line}" for line in call.warnings] if call.exit_code != 0: code = f"{STATUS_FAILED}:{INDEX_FAILED_PREFIX}{command}:{call.exit_code}" return _announce(target, IndexOutcome(code, call.reason, tuple(warnings), removed)) if plan.key is not None and plan.parts is not None: _write_key(target, plan.key, plan.parts) code = INDEX_WRITTEN if CMD_POLICY in plan.commands else INDEX_WRITTEN_DATASETS_ONLY return _announce(target, IndexOutcome(code, warnings=tuple(warnings), removed=removed)) def _announce(target: Target, outcome: IndexOutcome) -> IndexOutcome: """치운 디렉토리·색인 경고를 stderr 에 한 줄씩(경로·태그 이름·건수뿐 — 행 본문은 CLI 가 싣지 않는다).""" if outcome.removed: names = "·".join(f"{name}/" for name in outcome.removed) click.secho( f" 색인({target.case_ref}): lock·정책 템플릿이 없어 옛 {names} 를 치웠다", fg="yellow", err=True, ) for line in outcome.warnings: click.secho(f" 색인 경고({target.case_ref}) — {line}", fg="yellow", err=True) return outcome def _remove_stale_outputs(target: Target, plan: _Plan, root: Path) -> tuple[str, ...]: """건너뛴 명령이 예전에 쓴 출력 디렉토리를 지운다(리뷰 지적 2). 지운 디렉토리 이름을 돌려준다. lock·템플릿이 없다고 **확정**했을 때만(`plan.key` 가 있거나 명령이 0) — 못 읽어 세 명령을 모두 부르는 경우는 치울 것이 없다. 심볼릭 링크는 링크만 지운다(가리키는 곳은 건드리지 않는다). """ from poc_bundle.index.case import prune_skipped_lock_indexes return prune_skipped_lock_indexes(root, target.account, target.case, plan.commands) # ── 선행 판정·키 ───────────────────────────────────────────────────────── def _plan(target: Target) -> _Plan: """돌 명령과 키. lock 이 없으면 명령 0. 레이아웃·lock 을 못 읽으면 키 없이 세 명령(CLI 가 실패를 보고).""" from poc_bundle.data.data_root import build_case_layout, load_existing_lock from poc_bundle.data.errors import DataError try: layout = build_case_layout( target.repo_root, target.case_ref, projects_dir=target.projects_dir ) found = load_existing_lock(layout) except (DataError, OSError): return _Plan((CMD_DATASETS, CMD_TAGS, CMD_POLICY), None, None) if found is None: return _Plan((), None, None) template = _template_bytes(target) commands = (CMD_DATASETS,) if template is None else (CMD_DATASETS, CMD_TAGS, CMD_POLICY) parts = _key_parts(found[1], template) return _Plan(commands, _key_of(parts), parts) def _template_bytes(target: Target) -> bytes | None: """정책 템플릿(`index policy` 기본 위치) 바이트. 없으면 None. 있는데 못 읽으면 `OSError` 를 올린다(번들 다리가 보고).""" from poc_bundle.index.cli import TEMPLATE_DEFAULT path = target.repo_root / "accounts" / target.account / target.case / TEMPLATE_DEFAULT if not path.exists() and not path.is_symlink(): return None return path.read_bytes() def _key_parts(lock_bytes: bytes, template: bytes | None) -> dict[str, Any]: from poc_bundle.index.row_tags import EXTRACTOR return { "lock_sha": _sha256(lock_bytes), "template_sha": None if template is None else _sha256(template), "text_mode": optin.text_mode(), "extractor": EXTRACTOR, "index_code_sha": index_code_sha(), } def _key_of(parts: dict[str, Any]) -> str: from poc_bundle.canonical import jcs_bytes ordered = [ parts["lock_sha"], parts["template_sha"], parts["text_mode"], parts["extractor"], parts["index_code_sha"], ] return _sha256(jcs_bytes(ordered)) def index_code_sha(package_root: Path | None = None) -> str: """`poc_bundle` 패키지 전체 `*.py` 의 (상대 경로, 길이, 바이트)를 경로순으로 이은 sha256(검토 F9 · 리뷰 지적 3). 색인 출력은 `index/` 밖 PB 모듈(`keys.dataset_version` 등)에도 달려 있다 — 그래서 `index/` 만이 아니라 패키지 전체를 본다. `package_root` 는 시험용(기본은 설치된 `poc_bundle` 패키지 디렉토리). 경로를 섞어 이름 바꾸기·옮기기도 잡는다. """ if package_root is None: import poc_bundle package_root = Path(poc_bundle.__file__).parent digest = hashlib.sha256() sources = sorted( (p.relative_to(package_root).as_posix(), p) for p in package_root.rglob("*.py") ) for rel, path in sources: data = path.read_bytes() digest.update(f"{rel}\0{len(data)}\0".encode()) digest.update(data) return digest.hexdigest() def _sha256(data: bytes) -> str: return hashlib.sha256(data).hexdigest() def key_path(target: Target) -> Path: """`///hook/index-key.json`.""" from poc_bundle.home import hub_reports_dir return hub_reports_dir() / target.account / target.case / HOOK_DIRNAME / INDEX_KEY_FILENAME def _stored_key(target: Target) -> str | None: """저장된 키. 없거나 깨졌으면 None — 다시 만든다(키 파일은 캐시일 뿐이다).""" try: doc = json.loads(key_path(target).read_text("utf-8")) except (OSError, ValueError): return None key = doc.get("key") if isinstance(doc, dict) else None return key if isinstance(key, str) else None def _write_key(target: Target, key: str, parts: dict[str, Any]) -> None: """임시 파일 → `os.replace`(원자적). 실패는 호출자에게 올린다 — 조용히 삼키면 매번 다시 만든다는 사실이 숨는다.""" path = key_path(target) path.parent.mkdir(parents=True, exist_ok=True) doc = {"schema": INDEX_KEY_SCHEMA, "key": key, "parts": parts} tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp") tmp.write_text(json.dumps(doc, ensure_ascii=False, sort_keys=True) + "\n", "utf-8") os.replace(tmp, path) def _index_root() -> Path: from poc_bundle.home import hub_index_root return hub_index_root() def _unchanged(target: Target, plan: _Plan, root: Path) -> bool: if _stored_key(target) != plan.key: return False case_dir = root / "accounts" / target.account / target.case return all((case_dir / OUTPUT_DIRS[c]).is_dir() for c in plan.commands) # ── click 호출 ─────────────────────────────────────────────────────────── def command_args(target: Target, command: str, root: Path) -> list[str]: """색인 명령 하나의 인자 — 루트는 모두 명시한다(CLI 기본값을 거치지 않는다).""" from poc_bundle.index.case import lock_index_args return lock_index_args( command, target.case_ref, root, text_mode=optin.text_mode(), projects_dir=target.projects_dir, ) def invoke_index(args: Sequence[str]) -> IndexCall: """`poc-bundle index ` 를 `standalone_mode=False` 로 — 종료 코드, 실패면 click 문구 마지막 줄, stderr 경고 줄.""" from poc_bundle.index.cli import index_group sink_out, sink_err = io.StringIO(), io.StringIO() try: with contextlib.redirect_stdout(sink_out), contextlib.redirect_stderr(sink_err): rv = index_group.main(list(args), prog_name=PROG_NAME, standalone_mode=False) except click.ClickException as exc: return _call(exc.exit_code, sink_err, _last_line(exc.format_message())) except click.exceptions.Exit as exc: return _call(exc.exit_code, sink_err) except click.Abort: return _call(1, sink_err, "aborted") except SystemExit as exc: return _call(exc.code if isinstance(exc.code, int) else 1, sink_err) return _call(rv if isinstance(rv, int) and not isinstance(rv, bool) else 0, sink_err) def _call(exit_code: int, sink_err: io.StringIO, reason: str | None = None) -> IndexCall: """버퍼에서 경고 줄을 뽑아 결과를 만든다. 실패인데 이유가 없으면 stderr 마지막 줄을 이유로.""" text = sink_err.getvalue() if exit_code != 0 and reason is None: reason = _last_line(text) return IndexCall(exit_code, None if exit_code == 0 else reason, warning_lines(text)) def warning_lines(text: str) -> tuple[str, ...]: """stderr 버퍼에서 `warning:` 로 시작하는 줄(앞뒤 공백 제거)만.""" return tuple( line.strip() for line in text.splitlines() if line.strip().startswith(WARNING_PREFIX) ) def _last_line(text: str) -> str | None: lines = [line.strip() for line in text.splitlines() if line.strip()] return lines[-1] if lines else None