jihoson/The-Ouroboros
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

docs validator: add docs sync invariants with tests (#363) #365

Merged
jihoson merged 2 commits from feature/issue-363-validate-docs-sync into feature/v3-session-policy-stream 2026-03-01 23:12:17 +09:00
Conversation 3 Commits 2 Files Changed 4 +264
agentson commented 2026-03-01 23:04:01 +09:00
Collaborator
Copy Link

Summary

#363에 따라 문서 드리프트 방지를 위한 top-level docs sync validator를 추가했습니다.

Changes

  • scripts/validate_docs_sync.py (신규)
    • 필수 문서 파일 존재 검증 (README.md, CLAUDE.md, docs/commands.md, docs/testing.md, docs/workflow.md)
    • README/CLAUDE/commands/testing의 상대 링크 무결성 검증
    • README/CLAUDE가 core docs 링크를 포함하는지 검증
    • docs/commands.md API endpoint 테이블 중복 row 검증
    • docs/testing.md의 동적 테스트 카운트 가이드(pytest --collect-only -q) 존재 검증
  • tests/test_validate_docs_sync.py (신규)
    • endpoint 파싱
    • absolute/broken 링크 검출
    • core docs 링크 검증
    • endpoint 중복 검출
    • testing 동적 카운트 가이드 검증

Validation

  • ruff check scripts/validate_docs_sync.py tests/test_validate_docs_sync.py
  • pytest -q tests/test_validate_docs_sync.py (5 passed)
  • python3 scripts/validate_docs_sync.py

Scope

  • REQ: REQ-OPS-002, REQ-OPS-003
  • TASK: TASK-OPS-002, TASK-OPS-003
  • TEST: TEST-ACC-008, TEST-ACC-009

Closes #363

## Summary `#363`에 따라 문서 드리프트 방지를 위한 top-level docs sync validator를 추가했습니다. ## Changes - `scripts/validate_docs_sync.py` (신규) - 필수 문서 파일 존재 검증 (`README.md`, `CLAUDE.md`, `docs/commands.md`, `docs/testing.md`, `docs/workflow.md`) - README/CLAUDE/commands/testing의 상대 링크 무결성 검증 - README/CLAUDE가 core docs 링크를 포함하는지 검증 - `docs/commands.md` API endpoint 테이블 중복 row 검증 - `docs/testing.md`의 동적 테스트 카운트 가이드(`pytest --collect-only -q`) 존재 검증 - `tests/test_validate_docs_sync.py` (신규) - endpoint 파싱 - absolute/broken 링크 검출 - core docs 링크 검증 - endpoint 중복 검출 - testing 동적 카운트 가이드 검증 ## Validation - `ruff check scripts/validate_docs_sync.py tests/test_validate_docs_sync.py` - `pytest -q tests/test_validate_docs_sync.py` (`5 passed`) - `python3 scripts/validate_docs_sync.py` ## Scope - REQ: `REQ-OPS-002`, `REQ-OPS-003` - TASK: `TASK-OPS-002`, `TASK-OPS-003` - TEST: `TEST-ACC-008`, `TEST-ACC-009` Closes #363
agentson added 1 commit 2026-03-01 23:04:01 +09:00
docs validator: add validate_docs_sync with unit tests (#363)
All checks were successful
Gitea CI / test (push) Successful in 32s
Details
Gitea CI / test (pull_request) Successful in 32s
Details
51fd6b7a72
agentson commented 2026-03-01 23:07:09 +09:00
Author
Collaborator
Copy Link

코드 리뷰 — PR #365

개요

PR #352의 재작성 버전. 이번에는 테스트를 동반하며, docs/README.md 의존성을 제거해 독립적으로 동작한다. 5 passed, ruff clean, 직접 실행 PASS 확인.

🔴 수정 필요

1. CI 게이트 미등록

validate_docs_sync.py가 추가됐지만 .gitea/workflows/ci.yml과 .github/workflows/ci.yml 어디에도 실행 단계가 없다.

현재 등록된 validator들:

- name: Validate governance assets
  run: python3 scripts/validate_governance_assets.py
- name: Validate Ouroboros docs
  run: python3 scripts/validate_ouroboros_docs.py

validate_docs_sync.py가 없으면 PR을 머지해도 이 검증은 실행되지 않는다. 추가 필요:

- name: Validate docs sync
  run: python3 scripts/validate_docs_sync.py

🟡 확인 필요

2. validate_summary_docs_reference_core_docs — 음성 테스트 없음

현재 test_validate_summary_docs_reference_core_docs는 링크가 있을 때 errors == []만 확인한다. 링크가 빠졌을 때 에러가 발생하는지 검증하는 음성 케이스가 없다.

동일 기능의 다른 테스트들은 음성 케이스를 포함한다:

  • test_validate_links_resolve_detects_absolute_and_broken_links → 음성 ✅
  • test_validate_commands_endpoint_duplicates_reports_duplicates → 음성 ✅
  • test_validate_summary_docs_reference_core_docs → 양성만 ❌
def test_validate_summary_docs_reference_core_docs_reports_missing_link(monkeypatch) -> None:
    module = _load_module()
    errors: list[str] = []
    fake_docs = {
        str(module.REQUIRED_FILES["README.md"]): "docs/workflow.md",  # commands.md, testing.md 누락
        str(module.REQUIRED_FILES["CLAUDE.md"]): "docs/workflow.md docs/commands.md",
    }
    monkeypatch.setattr(module, "_read", lambda path: fake_docs[str(path)])
    module.validate_summary_docs_reference_core_docs(errors)
    assert any("docs/commands.md" in err for err in errors)
    assert any("docs/testing.md" in err for err in errors)

3. validate_summary_docs_reference_core_docs — ternary 불필요

required_links의 key가 "README.md", "CLAUDE.md"이고 REQUIRED_FILES도 동일 key를 가지므로 ternary가 필요 없다:

# 현재
doc_path = (
    REQUIRED_FILES["README.md"]
    if file_name == "README.md"
    else REQUIRED_FILES["CLAUDE.md"]
)

# 개선
doc_path = REQUIRED_FILES[file_name]

4. workflow.md 링크 검증 미포함

REQUIRED_FILES에 "workflow" 키로 docs/workflow.md가 등록됐지만, main()의 validate_links_resolve 호출 목록에서 빠져 있다. 존재 검증만 되고 내부 링크 무결성은 검증되지 않는다. 의도적 제외라면 REQUIRED_FILES에서 제거하거나 주석으로 명시하는 것이 낫다.

✅ 좋은 점

  • PR #352 핵심 결함 해결 — 테스트 동반, docs/README.md 외부 의존 제거
  • scope 깔끔 — 단일 커밋, 2개 파일
  • validate_links_resolve 설계 — absolute / broken / fragment 모두 처리
  • REPO_ROOT 명명 — PR #352의 ROOT보다 의도가 명확

수정 사항 요약

우선순위 위치 내용
🔴 .gitea/workflows/ci.yml, .github/workflows/ci.yml validate_docs_sync.py 실행 단계 추가
🟡 tests/test_validate_docs_sync.py validate_summary_docs_reference_core_docs 음성 테스트 추가
🟡 scripts/validate_docs_sync.py ternary → REQUIRED_FILES[file_name] 단순화, workflow.md 링크 검증 처리 결정
## 코드 리뷰 — PR #365 ### 개요 PR #352의 재작성 버전. 이번에는 테스트를 동반하며, `docs/README.md` 의존성을 제거해 독립적으로 동작한다. 5 passed, ruff clean, 직접 실행 PASS 확인. --- ### 🔴 수정 필요 #### 1. CI 게이트 미등록 `validate_docs_sync.py`가 추가됐지만 `.gitea/workflows/ci.yml`과 `.github/workflows/ci.yml` 어디에도 실행 단계가 없다. 현재 등록된 validator들: ```yaml - name: Validate governance assets run: python3 scripts/validate_governance_assets.py - name: Validate Ouroboros docs run: python3 scripts/validate_ouroboros_docs.py ``` `validate_docs_sync.py`가 없으면 PR을 머지해도 이 검증은 실행되지 않는다. 추가 필요: ```yaml - name: Validate docs sync run: python3 scripts/validate_docs_sync.py ``` --- ### 🟡 확인 필요 #### 2. `validate_summary_docs_reference_core_docs` — 음성 테스트 없음 현재 `test_validate_summary_docs_reference_core_docs`는 링크가 있을 때 `errors == []`만 확인한다. 링크가 빠졌을 때 에러가 발생하는지 검증하는 음성 케이스가 없다. 동일 기능의 다른 테스트들은 음성 케이스를 포함한다: - `test_validate_links_resolve_detects_absolute_and_broken_links` → 음성 ✅ - `test_validate_commands_endpoint_duplicates_reports_duplicates` → 음성 ✅ - `test_validate_summary_docs_reference_core_docs` → 양성만 ❌ ```python def test_validate_summary_docs_reference_core_docs_reports_missing_link(monkeypatch) -> None: module = _load_module() errors: list[str] = [] fake_docs = { str(module.REQUIRED_FILES["README.md"]): "docs/workflow.md", # commands.md, testing.md 누락 str(module.REQUIRED_FILES["CLAUDE.md"]): "docs/workflow.md docs/commands.md", } monkeypatch.setattr(module, "_read", lambda path: fake_docs[str(path)]) module.validate_summary_docs_reference_core_docs(errors) assert any("docs/commands.md" in err for err in errors) assert any("docs/testing.md" in err for err in errors) ``` #### 3. `validate_summary_docs_reference_core_docs` — ternary 불필요 `required_links`의 key가 `"README.md"`, `"CLAUDE.md"`이고 `REQUIRED_FILES`도 동일 key를 가지므로 ternary가 필요 없다: ```python # 현재 doc_path = ( REQUIRED_FILES["README.md"] if file_name == "README.md" else REQUIRED_FILES["CLAUDE.md"] ) # 개선 doc_path = REQUIRED_FILES[file_name] ``` #### 4. `workflow.md` 링크 검증 미포함 `REQUIRED_FILES`에 `"workflow"` 키로 `docs/workflow.md`가 등록됐지만, `main()`의 `validate_links_resolve` 호출 목록에서 빠져 있다. 존재 검증만 되고 내부 링크 무결성은 검증되지 않는다. 의도적 제외라면 `REQUIRED_FILES`에서 제거하거나 주석으로 명시하는 것이 낫다. --- ### ✅ 좋은 점 - **PR #352 핵심 결함 해결** — 테스트 동반, `docs/README.md` 외부 의존 제거 - **scope 깔끔** — 단일 커밋, 2개 파일 - **`validate_links_resolve` 설계** — absolute / broken / fragment 모두 처리 - **`REPO_ROOT` 명명** — PR #352의 `ROOT`보다 의도가 명확 --- ### 수정 사항 요약 | 우선순위 | 위치 | 내용 | |----------|------|------| | 🔴 | `.gitea/workflows/ci.yml`, `.github/workflows/ci.yml` | `validate_docs_sync.py` 실행 단계 추가 | | 🟡 | `tests/test_validate_docs_sync.py` | `validate_summary_docs_reference_core_docs` 음성 테스트 추가 | | 🟡 | `scripts/validate_docs_sync.py` | ternary → `REQUIRED_FILES[file_name]` 단순화, `workflow.md` 링크 검증 처리 결정 |
agentson added 1 commit 2026-03-01 23:09:21 +09:00
ci/docs: wire docs sync validator into workflows and tighten tests
All checks were successful
Gitea CI / test (push) Successful in 33s
Details
Gitea CI / test (pull_request) Successful in 35s
Details
6656adc2b7
agentson commented 2026-03-01 23:09:28 +09:00
Author
Collaborator
Copy Link

리뷰 반영 완료했습니다.

  • 🔴 CI 게이트 등록

    • .gitea/workflows/ci.yml: Validate docs sync 단계 추가
    • .github/workflows/ci.yml: Validate docs sync 단계 추가

  • 🟡 테스트 보강

    • tests/test_validate_docs_sync.py
    • test_validate_summary_docs_reference_core_docs_reports_missing_links 추가(음성 케이스)

  • 🟡 코드 정리/범위 명확화

    • scripts/validate_docs_sync.py
    • ternary 제거: doc_path = REQUIRED_FILES[file_name]
    • docs/workflow.md 링크 무결성 검증 포함

검증:

  • ruff check scripts/validate_docs_sync.py tests/test_validate_docs_sync.py
  • pytest -q tests/test_validate_docs_sync.py (6 passed)
  • python3 scripts/validate_docs_sync.py
  • python3 scripts/validate_governance_assets.py origin/feature/v3-session-policy-stream...HEAD

반영 커밋: 6656adc

리뷰 반영 완료했습니다. - 🔴 CI 게이트 등록 - .gitea/workflows/ci.yml: Validate docs sync 단계 추가 - .github/workflows/ci.yml: Validate docs sync 단계 추가 - 🟡 테스트 보강 - tests/test_validate_docs_sync.py - test_validate_summary_docs_reference_core_docs_reports_missing_links 추가(음성 케이스) - 🟡 코드 정리/범위 명확화 - scripts/validate_docs_sync.py - ternary 제거: doc_path = REQUIRED_FILES[file_name] - docs/workflow.md 링크 무결성 검증 포함 검증: - ruff check scripts/validate_docs_sync.py tests/test_validate_docs_sync.py - pytest -q tests/test_validate_docs_sync.py (6 passed) - python3 scripts/validate_docs_sync.py - python3 scripts/validate_governance_assets.py origin/feature/v3-session-policy-stream...HEAD 반영 커밋: 6656adc
agentson commented 2026-03-01 23:11:18 +09:00
Author
Collaborator
Copy Link

팔로업 리뷰 — PR #365 (커밋 6656adc2)

이슈 해결 확인

이슈 상태
🔴 CI 게이트 미등록 ✅ 해결
🟡 validate_summary_docs_reference_core_docs 음성 테스트 없음 ✅ 해결
🟡 ternary → REQUIRED_FILES[file_name] 단순화 ✅ 해결
🟡 workflow.md 링크 검증 미포함 ✅ 해결

세부 확인

CI 게이트: .gitea/workflows/ci.yml line 51, .github/workflows/ci.yml line 48에 validate_docs_sync.py 단계 등록 확인.

음성 테스트: test_validate_summary_docs_reference_core_docs_reports_missing_links 추가. README에서 docs/commands.md, docs/testing.md 누락, CLAUDE에서 docs/commands.md 누락 → 각각 에러 발생 검증. 3개 assertion 모두 경로 포함하여 명확.

ternary 제거: doc_path = REQUIRED_FILES[file_name]으로 단순화됨.

workflow.md 링크 검증: main()에서 validate_links_resolve(REQUIRED_FILES["workflow"], ...) 호출 추가됨.

실행 결과

  • pytest -q tests/test_validate_docs_sync.py: 6 passed
  • python3 scripts/validate_docs_sync.py: [OK]
  • ruff check: All checks passed

Merge-ready. 모든 지적 사항 해결됨.

## 팔로업 리뷰 — PR #365 (커밋 6656adc2) ### 이슈 해결 확인 | 이슈 | 상태 | |------|------| | 🔴 CI 게이트 미등록 | ✅ 해결 | | 🟡 `validate_summary_docs_reference_core_docs` 음성 테스트 없음 | ✅ 해결 | | 🟡 ternary → `REQUIRED_FILES[file_name]` 단순화 | ✅ 해결 | | 🟡 `workflow.md` 링크 검증 미포함 | ✅ 해결 | --- ### 세부 확인 **CI 게이트**: `.gitea/workflows/ci.yml` line 51, `.github/workflows/ci.yml` line 48에 `validate_docs_sync.py` 단계 등록 확인. **음성 테스트**: `test_validate_summary_docs_reference_core_docs_reports_missing_links` 추가. README에서 `docs/commands.md`, `docs/testing.md` 누락, CLAUDE에서 `docs/commands.md` 누락 → 각각 에러 발생 검증. 3개 assertion 모두 경로 포함하여 명확. **ternary 제거**: `doc_path = REQUIRED_FILES[file_name]`으로 단순화됨. **workflow.md 링크 검증**: `main()`에서 `validate_links_resolve(REQUIRED_FILES["workflow"], ...)` 호출 추가됨. --- ### 실행 결과 - `pytest -q tests/test_validate_docs_sync.py`: **6 passed** - `python3 scripts/validate_docs_sync.py`: **[OK]** - `ruff check`: **All checks passed** --- **Merge-ready.** 모든 지적 사항 해결됨.
jihoson merged commit 774ce8e94f into feature/v3-session-policy-stream 2026-03-01 23:12:17 +09:00
jihoson deleted branch feature/issue-363-validate-docs-sync 2026-03-01 23:12:17 +09:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something is not working
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 wontfix
This won't be fixed
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agentson jihoson
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jihoson/The-Ouroboros#365
Delete Branch "feature/issue-363-validate-docs-sync"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?