Files
clean-architecture-backend-…/docs/history/packages/websocket-superpowers-package/validate_websocket_docs.py
T
DongHyeonka 630f9b860a docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.

고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
  → docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
  원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.

옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.

위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.

검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
2026-11-07 12:15:45 +09:00

85 lines
3.7 KiB
Python

from __future__ import annotations
from pathlib import Path
import re
import sys
import zipfile
root = Path(__file__).resolve().parent
if (root / 'docs').exists():
design = root / 'docs/superpowers/specs/2026-08-14-websocket-realtime-connection-platform-design.md'
stable = root / 'docs/superpowers/plans/2026-08-14-websocket-realtime-connection-platform-implementation-plan.md'
advanced = root / 'docs/superpowers/plans/2026-08-14-websocket-advanced-capabilities-expansion-plan.md'
else:
design = Path('/mnt/data/websocket-realtime-connection-platform-design.md')
stable = Path('/mnt/data/websocket-realtime-connection-platform-implementation-plan.md')
advanced = Path('/mnt/data/websocket-advanced-capabilities-expansion-plan.md')
checks = []
def check(name, condition):
checks.append((name, bool(condition)))
for path in (design, stable, advanced):
check(f'exists:{path.name}', path.exists())
if not path.exists():
continue
text = path.read_text(encoding='utf-8')
check(f'code-fence:{path.name}', text.count('```') % 2 == 0)
check(f'no-placeholders:{path.name}', not re.search(r'\b(TODO|TBD|FIXME)\b', text))
check(f'nontrivial:{path.name}', len(text.splitlines()) > 300)
stable_text = stable.read_text(encoding='utf-8')
advanced_text = advanced.read_text(encoding='utf-8')
design_text = design.read_text(encoding='utf-8')
stable_tasks = [int(n) for n in re.findall(r'^### Task (\d+):', stable_text, re.M)]
advanced_tasks = [int(n) for n in re.findall(r'^### Task (\d+):', advanced_text, re.M)]
check('stable-task-sequence', stable_tasks == list(range(1, 54)))
check('advanced-task-sequence', advanced_tasks == list(range(1, 23)))
for label, text, expected in [('stable', stable_text, 53), ('advanced', advanced_text, 22)]:
sections = re.split(r'(?=^### Task \d+:)', text, flags=re.M)[1:]
check(f'{label}-task-count', len(sections) == expected)
for idx, section in enumerate(sections, 1):
for token in ['**Files:**', '**Interfaces:**', '**Implementation requirements:**',
'Step 1:', 'Step 2:', 'Step 3:', 'Step 4:', 'Step 5:',
'git commit -m']:
check(f'{label}-task-{idx}-{token}', token in section)
create_pattern = re.compile(r'^- Create: `([^`]+)`', re.M)
stable_paths = create_pattern.findall(stable_text)
advanced_paths = create_pattern.findall(advanced_text)
check('stable-create-unique', len(stable_paths) == len(set(stable_paths)))
check('advanced-create-unique', len(advanced_paths) == len(set(advanced_paths)))
check('stable-advanced-create-disjoint', set(stable_paths).isdisjoint(set(advanced_paths)))
required_design = [
'Inbound Evidence', 'Outbound Evidence', 'Connection Evidence',
'hyeonworks.realtime.v1.json', 'ONE_TIME_TICKET',
'APPLICATION_COMMITTED', 'WRITTEN_LOCALLY',
'Outbound Queue·Backpressure', 'Nginx', 'Tomcat', 'Jetty',
'Reactor Netty', 'WebSocket exactly-once', 'Appendix A'
]
for token in required_design:
check(f'design-token:{token}', token in design_text)
required_stable = [
'Commit 후 Response Loss', 'Slow Consumer', 'Browser Matrix',
'MVC·WebFlux Stack 상호 배타성', 'Stable Release Gate'
]
for token in required_stable:
check(f'stable-token:{token}', token in stable_text)
required_advanced = [
'Resume Token', 'Messaging 기반 Durable Replay', 'STOMP 1.2',
'RabbitMQ STOMP Broker Relay', 'HTTP/3 WebSocket Experimental',
'GraphQL WebSocket Transport Bridge'
]
for token in required_advanced:
check(f'advanced-token:{token}', token in advanced_text)
failed = [name for name, ok in checks if not ok]
print(f'checks={len(checks)} passed={len(checks)-len(failed)} failed={len(failed)}')
for name in failed:
print('FAIL', name)
sys.exit(1 if failed else 0)