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

docs validator: enforce source path policy for ouroboros plan links (#357) #360

Merged
jihoson merged 2 commits from feature/issue-357-docs-source-path-validator into feature/v3-session-policy-stream 2026-03-01 21:32:48 +09:00
Conversation 3 Commits 2 Files Changed 2 +132 -6
agentson commented 2026-03-01 21:11:44 +09:00
Collaborator
Copy Link

Summary

REQ-OPS-004에 맞춰 v2/v3 원본 계획 문서 링크를 docs/ouroboros/source/ 경로로 강제하는 자동 검증을 추가하고, 리뷰 피드백(중복 에러/fragment 처리)을 반영했습니다.

Changes

  • scripts/validate_ouroboros_docs.py
    • validate_plan_source_link() 추가
    • ouroboros_plan_v2.txt, ouroboros_plan_v3.txt 링크가 canonical target으로 resolve되는지 검사
    • 절대경로(/home/...) 금지
    • 루트 상대경로(../../ouroboros_plan_v*.txt) 금지
    • #fragment가 붙은 링크도 경로 부분을 분리해 정책 검증
    • invalid plan 링크에 대해서는 broken-link 중복 에러를 발생시키지 않도록 조정
  • tests/test_validate_ouroboros_docs.py
    • canonical source 경로 허용 테스트
    • 절대경로 금지 테스트
    • 루트 상대경로 금지 테스트
    • fragment suffix 허용 테스트
    • invalid plan 링크 중복 에러 방지 테스트

Validation

  • ruff check scripts/validate_ouroboros_docs.py tests/test_validate_ouroboros_docs.py
  • pytest -q tests/test_validate_ouroboros_docs.py (5 passed)
  • python3 scripts/validate_ouroboros_docs.py
  • python3 scripts/validate_governance_assets.py origin/feature/v3-session-policy-stream...HEAD

Scope

  • REQ: REQ-OPS-004
  • TASK: TASK-OPS-004
  • TEST: TEST-ACC-019

Closes #357

## Summary `REQ-OPS-004`에 맞춰 v2/v3 원본 계획 문서 링크를 `docs/ouroboros/source/` 경로로 강제하는 자동 검증을 추가하고, 리뷰 피드백(중복 에러/fragment 처리)을 반영했습니다. ## Changes - `scripts/validate_ouroboros_docs.py` - `validate_plan_source_link()` 추가 - `ouroboros_plan_v2.txt`, `ouroboros_plan_v3.txt` 링크가 canonical target으로 resolve되는지 검사 - 절대경로(`/home/...`) 금지 - 루트 상대경로(`../../ouroboros_plan_v*.txt`) 금지 - `#fragment`가 붙은 링크도 경로 부분을 분리해 정책 검증 - invalid plan 링크에 대해서는 broken-link 중복 에러를 발생시키지 않도록 조정 - `tests/test_validate_ouroboros_docs.py` - canonical source 경로 허용 테스트 - 절대경로 금지 테스트 - 루트 상대경로 금지 테스트 - fragment suffix 허용 테스트 - invalid plan 링크 중복 에러 방지 테스트 ## Validation - `ruff check scripts/validate_ouroboros_docs.py tests/test_validate_ouroboros_docs.py` - `pytest -q tests/test_validate_ouroboros_docs.py` (`5 passed`) - `python3 scripts/validate_ouroboros_docs.py` - `python3 scripts/validate_governance_assets.py origin/feature/v3-session-policy-stream...HEAD` ## Scope - REQ: `REQ-OPS-004` - TASK: `TASK-OPS-004` - TEST: `TEST-ACC-019` Closes #357
agentson added 1 commit 2026-03-01 21:11:44 +09:00
docs: enforce source path policy for ouroboros plan links (#357)
All checks were successful
Gitea CI / test (push) Successful in 32s
Details
Gitea CI / test (pull_request) Successful in 32s
Details
117657d13f
agentson commented 2026-03-01 21:15:41 +09:00
Author
Collaborator
Copy Link

PR #360 코드 리뷰

변경 요약: validate_ouroboros_docs.py에 plan 링크 경로 정책 검증 추가 (REQ-OPS-004 / TEST-ACC-019)

✅ 잘 된 점

경로 비교 방식이 올바르다.

resolved_target = (path.parent / normalized).resolve()
if resolved_target != expected_target:
    ...

.resolve()를 사용해 ../../ouroboros_plan_v2.txt 같은 상위 경로 우회를 정확히 잡아낸다. 단순 문자열 비교가 아닌 실제 경로 해석이므로 링크 형태가 달라도 canonical 위치가 맞으면 통과한다.

구조가 확장 가능하다.

ALLOWED_PLAN_TARGETS dict로 허용 경로를 선언적으로 관리해, v4 등이 추가될 때 한 곳만 수정하면 된다.

테스트 3개 직접 확인 — 3 passed.

🟡 절대경로 링크 시 에러 2개 중복 발생

절대경로 plan 링크(/home/...)를 validate_links로 검사하면 에러가 2개 생성된다:

- README.md: invalid plan link path -> /home/.../ouroboros_plan_v2.txt (use ./source/...)
- README.md: broken link -> /home/.../ouroboros_plan_v2.txt

흐름 분석:

def validate_links(path, text, errors):
    for m in LINK_PATTERN.finditer(text):
        link = m.group("link").strip()
        ...
        validate_plan_source_link(path, link, errors)  # ← 에러 추가 후 return
        if link.startswith("/"):
            target = Path(link)
        ...
        if not target.exists():
            errors.append(f"{path}: broken link -> {link}")  # ← 두 번째 에러

validate_plan_source_link가 early return해도 validate_links의 broken link 검사는 계속 실행된다. 기능 오류는 아니지만 사용자가 중복 에러 메시지를 받아 혼란스러울 수 있다.

수정 방법:

# 옵션 A: validate_plan_source_link가 bool 반환 → True면 broken link 체크 skip
if validate_plan_source_link(path, link, errors):
    continue

# 옵션 B: errors 개수를 비교해 증가 시 skip
before = len(errors)
validate_plan_source_link(path, link, errors)
if len(errors) > before:
    continue

🔵 PR 설명의 --ci 플래그가 실제로 무효함

Validation 항목에 다음이 기재돼 있다:

python3 scripts/validate_ouroboros_docs.py --ci

하지만 validate_ouroboros_docs.py의 main()에는 argparse가 없어 --ci 인수를 무시하고 그냥 통과한다. 코드 버그는 아니지만 문서가 오해를 유발한다. 다음번엔 --ci 없이 그냥 스크립트를 실행하면 된다.

🔵 PLAN_LINK_PATTERN이 fragment URL을 처리하지 못함

PLAN_LINK_PATTERN = re.compile(r"ouroboros_plan_v(?P<version>[23])\.txt$")

$ 앵커 때문에 ./source/ouroboros_plan_v2.txt#section 형태의 링크는 매칭되지 않아 검증을 건너뛴다. 현재 실제 사용 케이스는 없지만, 미래에 섹션 링크가 생기면 정책 우회가 가능해진다.

✅ 최종 판정

항목 상태
REQ-OPS-004 / TEST-ACC-019 구현 ✅
테스트 3 passed ✅
경로 비교 정확성 ✅
🟡 절대경로 이중 에러 노이즈, 블로커 아님
🔵 --ci 문서 오류 Minor
🔵 fragment URL 미처리 Minor, 현재 사용 없음

기능 목적을 달성했다. 이중 에러 문제를 이번 PR에서 수정하거나 별도 이슈로 등록하면 더 좋다. Merge 가능 상태.

## PR #360 코드 리뷰 **변경 요약**: `validate_ouroboros_docs.py`에 plan 링크 경로 정책 검증 추가 (REQ-OPS-004 / TEST-ACC-019) --- ### ✅ 잘 된 점 **경로 비교 방식이 올바르다.** ```python resolved_target = (path.parent / normalized).resolve() if resolved_target != expected_target: ... ``` `.resolve()`를 사용해 `../../ouroboros_plan_v2.txt` 같은 상위 경로 우회를 정확히 잡아낸다. 단순 문자열 비교가 아닌 실제 경로 해석이므로 링크 형태가 달라도 canonical 위치가 맞으면 통과한다. **구조가 확장 가능하다.** `ALLOWED_PLAN_TARGETS` dict로 허용 경로를 선언적으로 관리해, v4 등이 추가될 때 한 곳만 수정하면 된다. **테스트 3개 직접 확인 — 3 passed.** --- ### 🟡 절대경로 링크 시 에러 2개 중복 발생 절대경로 plan 링크(`/home/...`)를 `validate_links`로 검사하면 에러가 2개 생성된다: ``` - README.md: invalid plan link path -> /home/.../ouroboros_plan_v2.txt (use ./source/...) - README.md: broken link -> /home/.../ouroboros_plan_v2.txt ``` 흐름 분석: ```python def validate_links(path, text, errors): for m in LINK_PATTERN.finditer(text): link = m.group("link").strip() ... validate_plan_source_link(path, link, errors) # ← 에러 추가 후 return if link.startswith("/"): target = Path(link) ... if not target.exists(): errors.append(f"{path}: broken link -> {link}") # ← 두 번째 에러 ``` `validate_plan_source_link`가 early return해도 `validate_links`의 broken link 검사는 계속 실행된다. 기능 오류는 아니지만 사용자가 중복 에러 메시지를 받아 혼란스러울 수 있다. **수정 방법:** ```python # 옵션 A: validate_plan_source_link가 bool 반환 → True면 broken link 체크 skip if validate_plan_source_link(path, link, errors): continue # 옵션 B: errors 개수를 비교해 증가 시 skip before = len(errors) validate_plan_source_link(path, link, errors) if len(errors) > before: continue ``` --- ### 🔵 PR 설명의 `--ci` 플래그가 실제로 무효함 Validation 항목에 다음이 기재돼 있다: ``` python3 scripts/validate_ouroboros_docs.py --ci ``` 하지만 `validate_ouroboros_docs.py`의 `main()`에는 `argparse`가 없어 `--ci` 인수를 무시하고 그냥 통과한다. 코드 버그는 아니지만 문서가 오해를 유발한다. 다음번엔 `--ci` 없이 그냥 스크립트를 실행하면 된다. --- ### 🔵 PLAN_LINK_PATTERN이 fragment URL을 처리하지 못함 ```python PLAN_LINK_PATTERN = re.compile(r"ouroboros_plan_v(?P<version>[23])\.txt$") ``` `$` 앵커 때문에 `./source/ouroboros_plan_v2.txt#section` 형태의 링크는 매칭되지 않아 검증을 건너뛴다. 현재 실제 사용 케이스는 없지만, 미래에 섹션 링크가 생기면 정책 우회가 가능해진다. --- ### ✅ 최종 판정 | 항목 | 상태 | |------|------| | REQ-OPS-004 / TEST-ACC-019 구현 | ✅ | | 테스트 3 passed | ✅ | | 경로 비교 정확성 | ✅ | | 🟡 절대경로 이중 에러 | 노이즈, 블로커 아님 | | 🔵 --ci 문서 오류 | Minor | | 🔵 fragment URL 미처리 | Minor, 현재 사용 없음 | 기능 목적을 달성했다. 이중 에러 문제를 이번 PR에서 수정하거나 별도 이슈로 등록하면 더 좋다. **Merge 가능** 상태.
agentson added 1 commit 2026-03-01 21:20:06 +09:00
docs validator: handle plan link fragments and avoid duplicate link errors
All checks were successful
Gitea CI / test (push) Successful in 33s
Details
Gitea CI / test (pull_request) Successful in 32s
Details
d1ef79f385
agentson commented 2026-03-01 21:20:25 +09:00
Author
Collaborator
Copy Link

리뷰 반영 완료했습니다.

  • 중복 에러 제거: invalid plan link로 판정된 경우 broken link 추가 에러를 더하지 않도록 수정
  • fragment 처리: ./source/ouroboros_plan_v2.txt#... 형태도 경로 부분 분리해서 정책 검증
  • PR 본문 Validation 예시에서 불필요한 --ci 인자 제거

추가 테스트:

  • test_validate_plan_source_link_accepts_fragment_suffix
  • test_validate_links_avoids_duplicate_error_for_invalid_plan_link

검증:

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

반영 커밋: d1ef79f

리뷰 반영 완료했습니다. - 중복 에러 제거: invalid plan link로 판정된 경우 broken link 추가 에러를 더하지 않도록 수정 - fragment 처리: ./source/ouroboros_plan_v2.txt#... 형태도 경로 부분 분리해서 정책 검증 - PR 본문 Validation 예시에서 불필요한 --ci 인자 제거 추가 테스트: - test_validate_plan_source_link_accepts_fragment_suffix - test_validate_links_avoids_duplicate_error_for_invalid_plan_link 검증: - ruff check scripts/validate_ouroboros_docs.py tests/test_validate_ouroboros_docs.py - pytest -q tests/test_validate_ouroboros_docs.py (5 passed) - python3 scripts/validate_ouroboros_docs.py 반영 커밋: d1ef79f
agentson commented 2026-03-01 21:32:15 +09:00
Author
Collaborator
Copy Link

팔로업 리뷰 — commit d1ef79f 반영 확인

✅ 이전 지적사항 전부 해결됨

🟡 이중 에러 → 수정됨

validate_plan_source_link가 bool을 반환하도록 변경하고, validate_links에서 True 반환 시 continue로 broken link 체크를 건너뜀.

직접 검증:

[절대경로] 에러 수: 1 (기대: 1)  ✅
[fragment] 에러 수: 0 (기대: 0)  ✅
[canonical] 에러 수: 0 (기대: 0) ✅

반환값 의미도 명확하다: True = "plan link로 처리했으니 이후 체크 skip", False = "plan link 아니거나 정상 → 계속 진행".

🔵 fragment URL → 수정됨

link.split("#", 1)[0]으로 fragment를 제거한 뒤 경로 부분만 검증. 일반 링크에도 동일 처리가 적용되어, 존재하는 파일의 fragment 링크는 broken link 에러 없이 통과한다:

[존재파일+fragment] 에러 수: 0 ✅
[없는파일+fragment] 에러 수: 1 ✅

🔵 PR 설명 --ci 문서 오기재 → 수정됨

python3 scripts/validate_ouroboros_docs.py --ci → python3 scripts/validate_ouroboros_docs.py 로 교정됨.

테스트 3 → 5개로 확장

테스트 상태
test_validate_plan_source_link_accepts_canonical_source_path ✅
test_validate_plan_source_link_rejects_root_relative_path ✅
test_validate_plan_source_link_rejects_repo_root_relative_path ✅
test_validate_plan_source_link_accepts_fragment_suffix (신규) ✅
test_validate_links_avoids_duplicate_error_for_invalid_plan_link (신규) ✅

5 passed 직접 확인.

✅ 최종 판정

이전 리뷰에서 지적한 모든 항목이 해결됐다. Merge 가능 상태.

## 팔로업 리뷰 — commit d1ef79f 반영 확인 ### ✅ 이전 지적사항 전부 해결됨 --- **🟡 이중 에러 → 수정됨** `validate_plan_source_link`가 `bool`을 반환하도록 변경하고, `validate_links`에서 `True` 반환 시 `continue`로 broken link 체크를 건너뜀. 직접 검증: ``` [절대경로] 에러 수: 1 (기대: 1) ✅ [fragment] 에러 수: 0 (기대: 0) ✅ [canonical] 에러 수: 0 (기대: 0) ✅ ``` 반환값 의미도 명확하다: `True` = "plan link로 처리했으니 이후 체크 skip", `False` = "plan link 아니거나 정상 → 계속 진행". --- **🔵 fragment URL → 수정됨** `link.split("#", 1)[0]`으로 fragment를 제거한 뒤 경로 부분만 검증. 일반 링크에도 동일 처리가 적용되어, 존재하는 파일의 fragment 링크는 broken link 에러 없이 통과한다: ``` [존재파일+fragment] 에러 수: 0 ✅ [없는파일+fragment] 에러 수: 1 ✅ ``` --- **🔵 PR 설명 `--ci` 문서 오기재 → 수정됨** `python3 scripts/validate_ouroboros_docs.py --ci` → `python3 scripts/validate_ouroboros_docs.py` 로 교정됨. --- **테스트 3 → 5개로 확장** | 테스트 | 상태 | |--------|------| | `test_validate_plan_source_link_accepts_canonical_source_path` | ✅ | | `test_validate_plan_source_link_rejects_root_relative_path` | ✅ | | `test_validate_plan_source_link_rejects_repo_root_relative_path` | ✅ | | `test_validate_plan_source_link_accepts_fragment_suffix` (신규) | ✅ | | `test_validate_links_avoids_duplicate_error_for_invalid_plan_link` (신규) | ✅ | 5 passed 직접 확인. --- ### ✅ 최종 판정 이전 리뷰에서 지적한 모든 항목이 해결됐다. **Merge 가능** 상태.
jihoson merged commit f50833941c into feature/v3-session-policy-stream 2026-03-01 21:32:48 +09:00
jihoson deleted branch feature/issue-357-docs-source-path-validator 2026-03-01 21:32:48 +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#360
Delete Branch "feature/issue-357-docs-source-path-validator"

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?