ArxivJS Viewer

arxivjs 데이터 폴더에 정리된 논문을 VS Code에서 읽기 전용으로 열람하는 확장이다.

• 주제(폴더) 목록을 보여준다.
• 주제를 고르면 논문 목록과 메타 정보를 보여준다. 메타 정보는 제목, 저자, 연도, URL, 초록, 인용수, 출처다.
• 논문을 고르면 요약 마크다운 문서를 렌더링해서 보여준다. 수식과 표도 렌더링한다.

이 확장은 데이터 폴더의 파일을 절대 수정하지 않는다.

데이터 폴더(arxivjsdata)는 arxivjs 앱으로 만들고 편집한다. 논문 검색과 추가, 요약 문서 생성, 메타 정보 관리, 하이라이트가 모두 그 앱의 일이다. arxivjs 앱에서 바꾼 내용은 이 확장의 Reload 버튼을 눌러 반영한다.

현재 버전: 0.2.0. 설계와 개발 일정은 저장소의 DEV-PLAN.md를 참고한다. 바뀐 내용은 CHANGELOG.md에 적는다.

목차

• ArxivJS Viewer
  • 목차
  • 사용자 가이드
    • 요구 사항
    • 설치
      • 방법 1. Marketplace에서 설치
      • 방법 2. .vsix 파일로 설치
      • 방법 3. 제거
    • 데이터 폴더 설정
    • 사용 방법
    • 설정 항목
    • 명령 목록
    • 데이터 폴더 형식
    • 문제 해결
  • 개발자 가이드
    • 개발 환경 준비
    • 로컬에서 실행과 디버깅
    • 테스트
    • 성능 측정
    • 패키징 (.vsix 만들기)
    • Marketplace에 확장 등록 (게시)
      • 1단계. Azure DevOps 조직과 Personal Access Token(PAT) 만들기
      • 2단계. 게시자(Publisher) 확인
      • 3단계. vsce 로그인
      • 4단계. 게시
    • 버전 업데이트와 재게시
    • Open VSX에 등록 (선택)
    • 개발 시 주의 사항

사용자 가이드

요구 사항

• VS Code 1.90 이상
• arxivjs 데이터 폴더. 형식은 데이터 폴더 형식을 참고한다.

설치

다음 세 가지 방법 중 하나를 쓴다.

방법 1. Marketplace에서 설치

1. VS Code 왼쪽 Activity Bar에서 Extensions(Ctrl+Shift+X)를 연다.
2. ArxivJS Viewer를 검색한다. 게시자는 doosik71이다.
3. Install을 누른다.

명령줄에서는 code --install-extension doosik71.arxivjs-viewer로 설치한다.

방법 2. .vsix 파일로 설치

배포받은 arxivjs-viewer-<버전>.vsix 파일이 있을 때 쓴다.

1. Extensions 뷰를 연다.
2. 오른쪽 위 … 메뉴에서 **Install from VSIX...**를 선택한다.
3. .vsix 파일을 고른다.

명령줄에서 설치할 수도 있다.

code --install-extension arxivjs-viewer-0.1.0.vsix

방법 3. 제거

Extensions 뷰에서 ArxivJS Viewer를 찾아 Uninstall을 누른다. 명령줄에서는 다음과 같이 한다.

code --uninstall-extension doosik71.arxivjs-viewer

확장을 제거해도 데이터 폴더에는 아무 영향이 없다.

데이터 폴더 설정

처음 실행하면 Activity Bar의 ArxivJS 아이콘을 눌렀을 때 "데이터 폴더 선택" 버튼이 보인다.

1. 데이터 폴더 선택 버튼을 누른다. Command Palette(Ctrl+Shift+P)에서 ArxivJS: 데이터 폴더 선택을 실행해도 된다.
2. arxivjs 데이터 폴더(예: D:\dev\javascript\arxivjsdata)를 고른다.

settings.json에 직접 적을 수도 있다.

{
  "arxivjs.dataFolder": "D:\\dev\\javascript\\arxivjsdata"
}

사용 방법

ArxivJS (Activity Bar)
└─ TOPICS          [🏠 홈] [⟳ Reload] [📂 폴더 선택] [⚙ 설정]
   ▸ AI Healthcare
   ▾ Few-Shot Learning    (87)    ← 펼치면 논문 목록과 논문 수
      A Closer Look at ...   2019 · 2,737
      Domain-Agnostic ...    2019 · 1 · 문서 없음
      ...

1. 주제 목록(홈)
   • ArxivJS 뷰를 처음 열면 편집기 영역에 홈 페이지가 함께 열린다. 데이터 폴더의 모든 주제가 논문 수와 함께 나온다. 자동으로 열리지 않게 하려면 설정 arxivjs.openHomeOnStartup을 끈다.
   • 다시 열려면 TOPICS 제목줄의 🏠 버튼을 누르거나 ArxivJS: 주제 목록(홈) 열기를 실행한다.
   • 필터: 검색 칸에 낱말을 입력하면 이름에 그 낱말이 모두 들어 있는 주제만 남는다. 표시 이름과 폴더 이름(Large_Language_Model 같은) 모두에서 찾는다.
     • Enter: 보이는 첫 주제를 연다.
     • ↓: 첫 주제로 포커스를 옮긴다.
   • 정렬: 이름순 또는 논문 수순.
   • 주제를 누르면 Topic 패널이 열린다.
   • TOPICS 트리에서도 VS Code 기본 기능으로 찾을 수 있다. 트리를 클릭한 뒤 이름을 입력하거나 Ctrl+Alt+F를 누르면 된다.
2. 주제 보기: TOPICS 뷰에 데이터 폴더의 주제가 나타난다. 폴더 이름의 _는 공백으로 표시한다(Few-Shot_Learning → Few-Shot Learning).
3. 논문 목록 보기
   • 주제를 펼치면 논문 목록이 나온다. 각 논문 옆에는 연도 · 인용수가 표시된다. 요약 문서가 없는 논문에는 문서 없음이 붙는다.
   • 논문에 마우스를 올리면 저자, 연도, 인용수, 출처, URL, 초록 앞부분이 툴팁으로 나온다.
   • 메타 정보(json)를 읽지 못한 논문은 경고 아이콘으로 표시된다.
   • 주제를 클릭하면 Topic 패널이 열린다. 주제의 논문이 표(제목·저자, 연도, 인용수)로 나온다.
     • 정렬: 열 머리글(제목, 연도, 인용)을 누른다. 같은 열을 다시 누르면 방향이 바뀐다. 처음 정렬 기준은 설정 arxivjs.paperSort를 따른다. 연도나 인용수가 없는 논문은 방향과 관계없이 맨 뒤로 간다.
     • 필터: 검색 칸에 낱말을 입력하면 제목과 저자에 그 낱말이 모두 들어 있는 논문만 남는다. "요약 문서 있는 것만"을 켜면 .md가 없는 논문을 숨긴다.
     • 초록: 행의 초록 버튼으로 펼치고 접는다. 원문 버튼은 원문 URL을 브라우저로 연다.
     • 논문 제목을 누르면 Paper 패널이 열린다. 기본은 Topic 패널과 같은 편집기 그룹의 새 탭이다. 화면을 나눠 표와 논문을 함께 보려면 설정 arxivjs.paperPanelLocation을 beside로 바꾼다. 이때 논문은 오른쪽 그룹 하나에 모이고, 논문을 열 때마다 화면이 더 나뉘지는 않는다.
     • Reload 해도 정렬, 필터, 스크롤 위치, 펼친 초록은 그대로 유지된다.
4. 논문 읽기
   • 논문을 클릭하면 Paper 패널이 열린다. 기본은 논문마다 새 탭이고, 이미 열린 논문은 그 탭으로 이동한다. 탭 하나를 재사용하려면 설정 arxivjs.openInNewTab을 끈다.
   • 위쪽에는 메타 정보(제목, 저자, 연도, 인용수, 출처, 원문 링크)가 나오고, 아래에는 렌더링된 요약 문서가 나온다.
   • 요약 문서가 없는 논문은 초록을 대신 보여준다.
5. 원문 열기, 로컬 문서 열기
   • Paper 패널의 원문 열기를 누르면 외부 브라우저에서 논문 페이지가 열린다.
   • 그 오른쪽의 로컬 문서 열기를 누르면 데이터 폴더의 실제 .md 파일이 편집기에서 열린다. 이 버튼은 요약 문서가 있는 논문에만 나온다.
   • ⚠️ 이 편집기는 일반 편집기다. 고치고 저장하면 데이터 폴더의 파일이 바뀐다. 확장 자체는 아무것도 쓰지 않으며, 저장은 사용자가 직접 할 때만 일어난다. arxivjs 앱이 같은 파일을 다시 만들면 고친 내용이 덮어써질 수 있다.
   • 저장한 내용을 Paper 패널에 반영하려면 패널의 ⟳ Reload를 누른다.
   • 탭 아이콘은 홈(집), Topic 패널(목록), Paper 패널(문서)이 서로 다르다.
6. 다시 읽기(Reload)
   • 이 확장은 파일 변경을 자동으로 감지하지 않는다. 다른 앱에서 데이터를 추가하거나 고쳤다면 Reload 버튼을 눌러 다시 읽는다.
   • 버튼마다 다시 읽는 범위가 다르다.

설정 항목

명령 목록

Command Palette(Ctrl+Shift+P)에서 ArxivJS로 검색한다.

데이터 폴더 형식

데이터 폴더는 arxivjs 앱이 만드는 형식을 따른다. 폴더 안의 파일을 추가하거나 고치려면 arxivjs 앱을 쓴다. 이 확장은 읽기만 한다. 예외는 로컬 문서 열기로 연 편집기에서 사용자가 직접 저장하는 경우뿐이다.

<데이터 폴더>/
├── Few-Shot_Learning/                 # 주제 폴더
│   ├── a_closer_look_at_few_shot_classification.json   # 메타 정보
│   ├── a_closer_look_at_few_shot_classification.md     # 요약 문서
│   └── ...
└── ...

• 주제 폴더 이름은 영문자, 숫자, 언더스코어(_), 하이픈(-)만 쓸 수 있다. 이 규칙에 맞지 않는 폴더(예: .git)는 목록에 나오지 않는다.
• 논문마다 이름이 같은 .json과 .md 파일이 한 쌍을 이룬다.
• .txt, .hlt, .bak 등 다른 파일은 무시한다.

.json 메타 정보의 예:

{
  "title": "A Closer Look at Few-shot Classification",
  "authors": "Wei-Yu Chen, Yen-Cheng Liu, Zsolt Kira, Yu-Chiang Frank Wang, Jia-Bin Huang",
  "year": 2019,
  "url": "http://arxiv.org/abs/1904.04232v2",
  "abstract": "Few-shot classification aims to ...",
  "citation": 2737,
  "source": "arxiv"
}

문제 해결

개발자 가이드

개발 환경 준비

필요한 도구:

• Node.js 20 LTS 이상
• VS Code 1.90 이상
• Git

다음 명령으로 저장소를 받고 의존성을 설치한다.

git clone https://github.com/doosik71/arxivjs-extension.git
cd arxivjs-extension
npm install

주요 npm 스크립트:

로컬에서 실행과 디버깅

1. VS Code에서 프로젝트 폴더를 연다.
2. F5를 누르거나 Run and Debug에서 Run Extension을 선택한다. 그러면 확장이 로드된 Extension Development Host 창이 새로 열린다.
3. 새 창에서 ArxivJS: 데이터 폴더 선택으로 테스트 데이터 폴더를 지정한다. 기본은 test/fixtures/sample-data다.
4. 코드를 고친 뒤 Extension Development Host 창에서 Ctrl+R(Developer: Reload Window)을 누르면 바뀐 내용이 반영된다.

Webview를 디버깅하려면 Extension Development Host 창에서 Developer: Open Webview Developer Tools를 실행한다.

테스트

npm run lint
npm test
npm run test:integration

• 테스트 데이터는 test/fixtures/sample-data/에 있다. 어떤 경계 사례가 들어 있는지는 test/fixtures/README.md에 정리되어 있다.

• 통합 테스트(scripts/run-integration.mjs)는 다음 순서로 어떤 파일도 바뀌지 않았는지 검증한다.

  1. fixture의 모든 파일 경로, 크기, mtime, SHA-256을 기록한다.
  2. fixture를 OS 수준 읽기 전용으로 바꾼다. 이때 기존 파일에 쓰면 EPERM으로 실패한다.
  3. 테스트를 실행한다.
  4. 읽기 전용을 되돌린다.
  5. 기록과 비교해서 파일이 생기거나, 사라지거나, 바뀌었으면 실패로 처리한다.

• 통합 테스트는 기본으로 최신 안정판 VS Code에서 실행한다. 최소 지원 버전에서 확인하려면 다음처럼 실행한다.

  VSCODE_TEST_VERSION=1.90.0 npm run test:integration
  

성능 측정

npm run bench                            # fixture
npm run bench -- D:\dev\javascript\arxivjsdata   # 실데이터 (읽기만 한다)

다음 목표를 판정하고, 하나라도 넘으면 종료 코드 1로 끝난다.

그 밖에 모든 md 문서를 한 번씩 렌더링해서 시간 분포(p50, p95, 최대)와 렌더링 예외 건수를 보여준다.

패키징 (.vsix 만들기)

npm run package
# 내부적으로: vsce package --no-dependencies

• --no-dependencies: 확장은 esbuild로 번들하므로 node_modules를 넣지 않는다.
• README의 상대 링크는 vsce가 repository(GitHub) 주소 기준의 절대 링크로 바꾼다. 패키지에 들어가지 않는 파일(DEV-PLAN.md 등)은 링크하지 않고 이름만 적는다.

이 명령을 실행하면 프로젝트 루트에 arxivjs-viewer-<버전>.vsix가 생긴다. 이 파일을 방법 2로 설치하면 Marketplace 없이도 팀 내부에 배포할 수 있다.

package.json의 게시 관련 항목:

배포 패키지에 들어갈 필요가 없는 파일(src/, test/, node_modules/ 등)은 .vscodeignore에 등록한다.

Marketplace에 확장 등록 (게시)

Visual Studio Marketplace에 처음 게시하는 절차다. 최초 1회만 1~3단계를 거치면 된다.

1단계. Azure DevOps 조직과 Personal Access Token(PAT) 만들기

1. https://dev.azure.com에 Microsoft 계정으로 로그인한다. 조직이 없으면 새로 만든다.
2. 오른쪽 위 User settings → Personal access tokens → New Token을 누른다.
3. 다음과 같이 설정한다.
   • Organization: All accessible organizations
   • Scopes: Custom defined → Show all scopes → Marketplace → Manage 체크
   • Expiration: 원하는 기간
4. 만든 토큰을 안전한 곳에 복사해 둔다. 이 창을 닫으면 다시 볼 수 없다.

2단계. 게시자(Publisher) 확인

이 확장의 게시자는 doosik71이다. 이미 만들어져 있고, package.json의 publisher에 적혀 있다.

다른 게시자로 배포하려면 다음과 같이 한다.

1. https://marketplace.visualstudio.com/manage에 같은 계정으로 로그인한다.
2. Create publisher를 누르고 ID와 이름을 입력한다. ID는 나중에 바꿀 수 없다.
3. 그 ID를 package.json의 publisher에 적는다.

3단계. vsce 로그인

npx @vscode/vsce login doosik71
# 프롬프트에 1단계의 PAT를 붙여넣는다.

4단계. 게시

npx @vscode/vsce publish

• 이미 만든 .vsix가 있으면 npx @vscode/vsce publish --packagePath arxivjs-viewer-0.2.0.vsix로 그 파일을 올릴 수 있다.
• 웹에서 올릴 수도 있다. https://marketplace.visualstudio.com/manage에서 게시자를 고르고 New extension → Visual Studio Code로 .vsix를 업로드한다.
• 게시 후 검증을 거쳐 몇 분 안에 Marketplace 검색에 나타난다. 확장 ID는 doosik71.arxivjs-viewer다.

Azure DevOps의 PAT 정책은 바뀔 수 있다. 위 방법이 막히면 공식 문서 Publishing Extensions를 확인한다. Microsoft Entra ID 인증을 쓰는 vsce publish --azure-credential 방식도 그 문서에 안내되어 있다.

버전 업데이트와 재게시

npx @vscode/vsce publish patch   # 0.2.0 → 0.2.1
npx @vscode/vsce publish minor   # 0.2.0 → 0.3.0
npx @vscode/vsce publish 1.0.0   # 버전 직접 지정

publish patch|minor|major는 package.json의 버전을 올리고 git 태그를 만든 뒤 게시한다. 게시 전에 CHANGELOG.md를 갱신한다.

Marketplace에서 확장을 내리려면 npx @vscode/vsce unpublish doosik71.arxivjs-viewer를 실행한다. 이 작업은 되돌릴 수 없다.

Open VSX에 등록 (선택)

VSCodium, Cursor 같은 VS Code 호환 에디터 사용자에게도 배포하려면 Open VSX에 게시한다.

1. https://open-vsx.org에 GitHub 계정으로 로그인하고, Eclipse Foundation Publisher Agreement에 동의한다.
2. 사용자 설정에서 Access Token을 만든다.
3. 다음 명령을 실행한다.

npx ovsx create-namespace doosik71 -p <token>   # 최초 1회
npx ovsx publish arxivjs-viewer-0.2.0.vsix -p <token>

개발 시 주의 사항

• 실사용 데이터 폴더에 쓰지 않는다.
  • 실제 데이터 폴더(예: D:\dev\javascript\arxivjsdata)는 열람용으로만 지정한다.
  • 테스트, 스크립트, markdownlint --fix 같은 자동 수정 도구가 그 경로를 대상으로 삼으면 안 된다.
  • 테스트는 항상 test/fixtures/ 아래의 복사본으로 한다.
• 데이터 폴더 접근은 src/data/readonlyFs.ts를 거쳐서만 한다. 이 모듈은 읽기 API만 노출한다. ESLint가 다른 곳에서 fs를 쓰거나 쓰기 API를 호출하면 오류를 낸다.
• 캐시나 사용자 상태는 context.globalState나 context.globalStorageUri에 저장한다. 데이터 폴더에는 아무 파일도 만들지 않는다.
• 설계 상세는 저장소의 DEV-PLAN.md를 따른다.