fix: 글이 조용히 깨지거나 일시 오류로 배포가 멈추는 경우 막기

[seungwonme]

요약

작성자 표시(#15)를 붙인 뒤 점검에서 나온 네 가지를 고칩니다. 지금 운영 중인 글에는 문제가 없고, 조건이 맞으면 생길 수 있던 문제를 코드로 막습니다.

문제	고친 방법
PR 단계에서 빌드 검사를 하지 않아 오류가 합친 뒤에야 드러났다	PR마다 배포와 같은 액션으로 빌드한다(check.yml). 배포는 하지 않는다
GitHub API가 잠깐 오류를 내면 배포 빌드가 바로 멈췄다	배포 빌드에서 일시 오류는 2초, 5초 뒤에 두 번까지 다시 요청한다
pubDatetime이 미래면 글이 조용히 빠졌다. 시간대를 빼면 9시간 늦게 발행됐다	빌드가 막는다
## 목차 뒤 문장, raw <details>, public/ 이미지, GIF가 빌드를 그냥 통과했다	빌드가 막는다

바뀐 것

• src/utils/checkPosts.ts(새 파일): 빌드 시작 전에 초안을 뺀 모든 글을 검사하는 Astro 통합입니다. 걸리면 파일과 줄을 알려 주고 빌드를 멈춥니다.
  • 로컬 pnpm build, PR 검사, 배포 빌드가 모두 거칩니다. 웹 편집기로 main에 바로 저장한 글도 배포 빌드에서 걸리고, 사이트는 이전 배포에 머뭅니다
  • 목차 판정은 remark-toc와 같은 src/utils/toc.ts 규칙을 씁니다
  • 코드 블록과 인라인 코드 안은 예시로 보고 검사하지 않습니다
• astro.config.ts: 위 검사를 integrations에 넣었습니다
• src/utils/postAuthors.ts: 재시도를 넣었습니다. 5xx, 10초 시간 초과, 1분 이하의 retry-after만 다시 요청합니다. 404나 시간당 한도 소진은 바로 멈춥니다. 로컬 빌드는 실패해도 작성자 줄만 빠지므로 다시 요청하지 않습니다
• .github/workflows/check.yml(새 파일): PR 빌드입니다. deploy.yml과 같은 withastro/action@v6을 써서 여기서 통과하면 배포 빌드도 통과합니다
• AGENTS.md: 발행 흐름을 PR로 바꾸고, 발행 시각 규칙과 "빌드가 막는 것" 절, 봇 발행과 일괄 수정 주의점을 적었습니다

커밋은 항목별로 나눴습니다(fix, feat, ci, docs).

검증

• 지금 글 2편으로 로컬 pnpm build: astro check 오류, 경고, 힌트 0. [check-posts] 글 2편 검사 통과. 빌드와 검색 색인 정상
• 규칙을 어긴 임시 글로 실제 astro build: 3건을 파일과 줄 번호로 알리고 멈췄습니다. 임시 글은 지웠습니다
• 가짜 글 25편과 GIF 파일 1개로 검사 판정: 전부 기대대로
• 목차 판정 24건을 실제 remark-toc(mdast-util-toc 7.1.0)가 지우는 노드와 대조: 전부 일치
• 가짜 GitHub API 서버로 재시도 8가지: 전부 기대대로
• 이 PR에서 새 검사 워크플로(run 36680979803)가 49초 만에 통과했습니다.
  로그에 [check-posts] 글 2편 검사 통과가 찍혔고, 결과물의 두 글 모두 작성: Aiden / 최근 수정: Aiden입니다

검사 판정 경우

경우	기대
정상 글(목차 바로 뒤에 절, @/assets 이미지)	통과
## 목차 뒤 문장, 목차 뒤 ### 소절	걸림
뒤에 제목이 없거나 h1만 있어 목차가 안 생기는 글	통과
## Table of Contents, ## **목차**	걸림
목차 뒤 HTML 주석만 있음, 인용 안의 ## 목차	통과
코드 블록, 네 개 울타리 안 세 개 울타리, 콜아웃 안 코드 블록	통과
raw <details>, 하위 폴더 글의 <details>	걸림
인라인 코드 안 <details>	통과
/로 시작하는 이미지(마크다운, <img>, 콜아웃 안)	걸림
로컬 GIF 참조, src/assets와 public의 GIF 파일	걸림
외부 주소 GIF	통과
1시간 뒤 발행	걸림
10분 뒤 발행(여유 15분 안), 따옴표와 줄 끝 주석, modDatetime: null	통과
시간대 없는 발행 시각, 날짜만 적은 발행 시각, 시간대 없는 modDatetime	걸림
초안, _로 시작하는 파일	건너뜀

재시도 경우

경우	결과
CI, 502 두 번 뒤 정상	성공, 요청 3회, 7초
CI, 계속 503	빌드 중단, 요청 3회, 7초
CI, 429 retry-after: 1	성공, 요청 2회, 1초
CI, 429 retry-after: 120	기다리지 않고 중단, 요청 1회
CI, 시간당 한도 소진 403	바로 중단, 요청 1회
CI, 404	바로 중단, 요청 1회
CI, 10초 넘게 응답 없음	성공, 요청 2회, 12초
로컬, 502	다시 요청하지 않고 작성자 줄만 뺌

리뷰 포인트

1. 미래 pubDatetime은 배포 빌드도 멈춥니다. 웹 편집기로 미래 시각의 글을 저장하면 시각을 고치거나 그 시각이 지나 다시 배포할 때까지 다른 변경도 배포되지 않습니다. 글이 조용히 빠지는 것보다 낫다고 판단했습니다
2. check.yml은 배포 액션을 그대로 써서 PR마다 Pages용 아티팩트를 한 번 올립니다. 배포에는 쓰이지 않고 하루 뒤 지워집니다
3. 이 검사를 저장소의 필수 검사로 지정하지는 않았습니다. 지정하면 검사가 실패한 PR은 합칠 수 없지만, 웹 편집기의 main 직접 커밋도 막힐 수 있어 따로 정할 일입니다
4. 병합하면 바로 운영 사이트에 배포됩니다