chore: 기여자용 문서 정합성 검사 스크립트 scripts/docs_lint.py 추가 (#725)

[EricSeokgon]

변경 유형 (Type of Change)

• 신규 문서 추가 (docs/new)
• 기존 문서 보완 (docs/update)
• 문서 오류 수정 (fix)
• 이미지 추가/수정 (assets)
• 빌드/설정/기타 (chore)

변경 내용 (Description)

#725에서 말씀해 주신 대로 스크립트를 작성해 PR로 올립니다. 기여자가 제출 전에 스스로 돌려보는 로컬 검사 도구이며, 문서 파일은 하나도 건드리지 않습니다.

scripts/docs_lint.py 1개 파일만 추가합니다 (119줄).

규칙	검사 내용
L1	목차 요약이 …로 절단됨 (#716에서 지적된 문장 단위 발췌 규칙)
L2	상대링크 대상 파일 부재
L3	frontmatter 부재 / title 누락
L4	제목 레벨 건너뜀 (h2 → h4 등)
L5	관련소스 클래스 참조가 실제 소스에 없음 (--src 지정 시에만)

python3 scripts/docs_lint.py .
python3 scripts/docs_lint.py . --json
python3 scripts/docs_lint.py . --src ../egovframe-common-components

관련 이슈 (Related Issues)

Refs #725

변경 영역 (Affected Areas)

• 개발환경 (egovframe-development/)
• 실행환경 (egovframe-runtime/)
• 공통컴포넌트 (common-component/)
• 기타 (README, 설정 파일 등) — scripts/ 신규

체크리스트 (Checklist)

• Push 전에 Pull을 했습니다.
• frontmatter의 title, url, menu, weight 등을 검토했습니다. (문서 변경 없음)
• 오탈자 및 맞춤법을 검토했습니다.
• 이미지 및 링크 경로가 올바른지 확인했습니다. (문서 변경 없음)
• 변경 영역 외 디렉토리에 불필요한 변경이 포함되지 않았습니다.

실행 결과 (현재 main 전수 검사)

$ python3 scripts/docs_lint.py .
files scanned: 672 / findings: 157 {'L2': 13, 'L3': 1, 'L2-siteok': 142, 'L4': 1}

157건 중 142건은 L2-siteok(정보성) 입니다. ./images/foo.png처럼 상위 섹션의 images/를 참조하는 패턴은 Hugo 렌더링 사이트에서는 정상이고 GitHub 뷰에서만 깨져 보이므로, 오탐으로 보고하지 않고 따로 분류합니다. 과거 link-check CI가 이런 패턴 때문에 소음이 컸던 점을 반영한 설계입니다.

실제로 확인이 필요한 것은 15건이며, 전부 수동으로 실존 여부를 대조했습니다(오탐 0건).

규칙	건수	예시
L2	13	egovframe-runtime/intro.md → ./presentation-layer/uxui-controller-component.md (해당 파일 없음), foundation-layer·batch-layer 4개 문서 → ../../runtime-example/... (runtime-example/ 디렉토리 자체가 없음)
L3	1	egovframe-runtime/intro.md frontmatter 없음
L4	1	common-component/user-authentication/find-id-password.md — ## 개요 다음이 #### 기능흐름 (h2→h4)

이번 PR은 스크립트 추가만 다루며 위 15건 수정은 포함하지 않았습니다. 필요하시면 별도 PR로 정리하겠습니다.

검증 (Validation)

• 실행 환경: Python 3.10.12 / Ubuntu. 표준 라이브러리만 사용하고 설치·의존성이 없습니다 (import re, os, sys, glob, json, urllib.parse + collections.defaultdict).
• 현재 main 전수 실행(672개 .md) 정상 완료, 종료 코드 0.
• --json 출력 파싱 정상, --src 경로 지정 시 L5 동작 확인.
• 인자 오류 처리 확인: 인자 없음 / 존재하지 않는 경로 / --src 값 누락 → usage 출력 후 종료 코드 2.

추가 참고 사항 (Additional Notes)

• CI는 건드리지 않았습니다. .github/workflows/에 변경이 없고, 워크플로에서 이 스크립트를 호출하지도 않습니다. 실행은 전적으로 기여자 수동입니다.
• 자동 머지 워크플로(merge-on-pr.yaml)의 paths는 **.md와 이미지 확장자만 대상으로 하므로, .py 파일만 있는 이 PR은 워크플로가 트리거되지 않고 Open 상태로 남습니다. 말씀하신 대로 센터 확인 후 처리 부탁드립니다.
• 기본 동작은 보고 전용(종료 코드 0) 입니다. 게이트로 쓰실 의향이 있으시면 하드 결함 발견 시 1을 반환하는 --strict 옵션을 후속 PR로 추가하겠습니다. 이번에는 제안 범위대로 두었습니다.
• 규칙 임계값이나 분류 방식에 조정이 필요하면 알려 주시면 반영하겠습니다. 감사합니다.