stalelink

링크 스캔

stalelink scan 명령을 통해 지정된 디렉터리 내의 모든 지원 문서 파일을 재귀적으로 검사합니다. 기본 출력 형식은 표 형태이며, 발견된 문제점만 표준 출력으로 보고됩니다. 진행 상황 및 진단 정보는 표준 오류로 출력되며, –quiet 옵션으로 이를 숨길 수 있습니다.

다중 출력 형식 지원

–format json 옵션을 사용하면 기계가 읽기 쉬운 JSON 보고서를 생성할 수 있으며, –format sarif 옵션으로는 코드 스캔 도구와의 연동을 위한 SARIF 형식 결과를 출력할 수 있습니다. 이 두 형식 모두 발견된 링크 문제만을 포함하며, 추가적인 디버그 정보는 표준 오류로 분리됩니다.

링크 수정 기능

stalelink fix 명령은 발견된 링크 문제를 미리 보기(unified diff)로 보여준 후, –write 및 –backup 옵션을 통해 실제 파일에 적용할 수 있습니다. 이 기능은 Markdown, 텍스트, HTML, DOCX, XLSX, PPTX, PDF 주석을 지원하며, 암호화되거나 서명된 PDF는 처리하지 않습니다. 수정된 파일은 다시 파싱해 무결성을 검증하고, 검증 실패 시 원본으로 복원합니다.

캐시 및 구성 관리

stalelink은 검사 결과를 로컬 SQLite 캐시에 저장하여 재검사 시 네트워크 요청을 줄입니다. 캐시의 TTL은 stalelink.toml 파일에서 설정할 수 있으며, 기본값은 24시간입니다. 환경 변수(STALELINK_*), 토플 파일, CLI 플래그 순으로 설정이 적용됩니다. 캐시 통계 조회 및 삭제는 stalelink cache stats 및 stalelink cache clear 명령으로 수행할 수 있습니다.

다운로드·설치 방법

Windows 사용자는 다음 방법 중 하나를 통해 stalelink을 설치할 수 있습니다.

• winget: winget install jishnuteegala.stalelink
• Scoop: 먼저 버킷을 추가한 후 scoop install stalelink 실행

  scoop bucket add jishnuteegala https://github.com/jishnuteegala/scoop-bucket

• Chocolatey (대기 중): choco install stalelink
• 수동 설치: GitHubリリース 페이지에서 stalelink-x86_64-pc-windows-msvc.zip 또는 ARM64용 stalelink-aarch64-pc-windows-msvc.zip을 다운로드 후 압축 해제
• Cargo: cargo install stalelink (Rust 툴체인 필요)
• npm: npm install -g @jishnuteegala/stalelink

첫 번째 공식 릴리스(v0.1.0)부터 패키지 관리자 채널이 활성화되며,それ以前에는 소스에서 직접 빌드해야 합니다.

기본 사용법/명령어

설치 후, 문서가 있는 디렉터리에서 링크 검사를 시작할 수 있습니다.

• 기본 스캔: stalelink scan docs/
• JSON 보고서 생성: stalelink scan --format json docs/ > report.json
• SARIF 형식 출력: stalelink scan --format sarif docs/ -o stalelink.sarif
• 진행 상황 숨기기: stalelink scan --quiet docs/
• 색상 출력 제어: stalelink scan --color never docs/ (터미널이 아닐 때 유용)

링크 수정을 원할 경우:

• 변경 사항 미리 보기: stalelink fix handbook/
• 변경 사항 적용 및 백업 생성: stalelink fix handbook/ --write --backup
• 복사본으로 수정 (원본 보존): stalelink fix handbook/ --copy

인증이 필요한 링크를 확인하려면 기본적으로 브라우저 쿠키를 사용하며, 이는 elevated Windows 프롬프트에서 실행해야 할 수 있습니다. 쿠키 사용을 원하지 않으면 --auth off 옵션으로 순수 HTTP 모드로 전환할 수 있습니다.

이런 경우에 유용합니다

내부 문서 포털, 기술 매뉴얼, 교육 자료, 또는 법적/규제 문서를 관리하는 팀은 stalelink을 사용해 배포 전이나 정기 점검 시 링크 상태를 자동으로 검사할 수 있습니다. 특히 인트라넷이나 SSO 보호 위키와 같이 로그인이 필요한 링크가 많은 환경에서는, 사용자의 실제 인증 상태를 반영해 오탐지를 줄이는 것이 큰 장점입니다. 개인이 장기간 보관한 연구 노트나 프로젝트 아카이브에서도, 외부 링크의 썩음(link rot)을 사전에 발견해 유지 관리 비용을 줄일 수 있습니다.

지원 환경·시스템 요구사항

stalelink은 Windows x86_64 및 ARM64 아키텍처용 사전 빌드 바이너리를 제공합니다. Rust 기반 도구로서, 소스에서 빌드하려면 안정적인 Rust 툴체인(1.56 이상)이 필요합니다. 추가적인 시스템 의존성은 없으며, 모든 기능은 단일 실행 파일에 포함되어 있습니다.

최신 버전·업데이트

현재 최신 버전은 0.1.0이며, 이는 첫 번째 공식 태그 릴리스입니다. 이 버전부터 winget, Scoop, Chocolatey 등의 Windows 패키지 관리자 채널을 통해 배포가 시작됩니다. 업데이트는 동일한 채널을 통해 이루어지며, 수동 설치 시에는 최신リリース 페이지에서 새 바이너리를 다운로드해 교체해야 합니다.

제한 사항·확인 사항

stalelink은 암호화되거나 서명된 PDF 문서 내의 링크는 처리하지 않습니다. 이는 보안상의 이유로 암호 해독이나 서명 검증을 수행하지 않기 때문입니다. 또한, 브라우저 쿠키를 사용하는 인증 모드(–auth browser)는 live-browser 기능으로 빌드된 경우에만 사용할 수 있으며, 기본 배포판에서는 이 기능이 비활성화되어 있습니다. 캐시는 기본적으로 플랫폼 캐시 디렉터리에 저장되며, 수동으로 위치를 변경하려면 stalelink.toml 파일을 수정해야 합니다.

FAQ

• stalelink은 원격 서버에 데이터를 전송합니까?

  아니요. stalelink은 완전히 로컬에서 동작하며, 사용자가 지정한 링크에만 네트워크 요청을 보내고 결과를 로컬 캐시에 저장합니다. 원격 분석이나 원격 분석은 수행하지 않습니다.

• Windows에서 winget으로 설치하려면 어떤 조건이 필요한가요?

  winget 설치는 Microsoft Store에 첫 번째 제출이 승인된 후에 작동합니다. 현재는 소스에서 빌드하거나 다른 패키지 관리자를 사용하는 것이 권장됩니다.

• 인증이 필요한 링크를 확인하려면 관리자 권한이 필요한가요?

  일부 브라우저(예: Chrome)의 앱 바운드 쿠키에 접근하려면 elevated Windows 프롬프트에서 실행해야 할 수 있습니다. 이는 운영체제의 보안 제한 때문이며, stalelink 자체의 요구사항은 아닙니다.