repo-atlas-cli 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +308 -0
  3. package/README.md +305 -2
  4. package/dist/app/atlas.d.ts +52 -0
  5. package/dist/app/atlas.js +99 -0
  6. package/dist/cli/main.d.ts +2 -0
  7. package/dist/cli/main.js +11 -0
  8. package/dist/cli/program.d.ts +4 -0
  9. package/dist/cli/program.js +175 -0
  10. package/dist/cli/render.d.ts +16 -0
  11. package/dist/cli/render.js +85 -0
  12. package/dist/extract/code.d.ts +4 -0
  13. package/dist/extract/code.js +283 -0
  14. package/dist/extract/facts.d.ts +57 -0
  15. package/dist/extract/facts.js +3 -0
  16. package/dist/extract/index.d.ts +7 -0
  17. package/dist/extract/index.js +86 -0
  18. package/dist/extract/parser.d.ts +3 -0
  19. package/dist/extract/parser.js +21 -0
  20. package/dist/extract/sql.d.ts +12 -0
  21. package/dist/extract/sql.js +86 -0
  22. package/dist/extract/text.d.ts +5 -0
  23. package/dist/extract/text.js +74 -0
  24. package/dist/graph/graph.d.ts +12 -0
  25. package/dist/graph/graph.js +41 -0
  26. package/dist/graph/types.d.ts +23 -0
  27. package/dist/graph/types.js +17 -0
  28. package/dist/indexer/aliases.d.ts +5 -0
  29. package/dist/indexer/aliases.js +104 -0
  30. package/dist/indexer/indexer.d.ts +27 -0
  31. package/dist/indexer/indexer.js +118 -0
  32. package/dist/indexer/link.d.ts +27 -0
  33. package/dist/indexer/link.js +340 -0
  34. package/dist/indexer/walk.d.ts +14 -0
  35. package/dist/indexer/walk.js +80 -0
  36. package/dist/mcp/server.d.ts +8 -0
  37. package/dist/mcp/server.js +69 -0
  38. package/dist/query/context.d.ts +30 -0
  39. package/dist/query/context.js +68 -0
  40. package/dist/query/impact.d.ts +28 -0
  41. package/dist/query/impact.js +63 -0
  42. package/dist/query/mermaid.d.ts +17 -0
  43. package/dist/query/mermaid.js +77 -0
  44. package/dist/query/path.d.ts +11 -0
  45. package/dist/query/path.js +32 -0
  46. package/dist/query/resolve.d.ts +17 -0
  47. package/dist/query/resolve.js +81 -0
  48. package/dist/query/stats.d.ts +14 -0
  49. package/dist/query/stats.js +22 -0
  50. package/dist/store/store.d.ts +27 -0
  51. package/dist/store/store.js +88 -0
  52. package/package.json +61 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Trapa-Eureka
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.ko.md ADDED
@@ -0,0 +1,308 @@
1
+ # Repo Atlas
2
+
3
+ [English](README.md) · **한국어**
4
+
5
+ > 이 문서는 [README.md](README.md)의 한국어 번역입니다. 두 문서가 다르면 영문이 기준입니다.
6
+
7
+ 저장소의 파일, 함수, SQL 테이블, 환경변수 키, 문서가 서로 어떻게 이어져 있는지 지도로 만들어 주는 로컬 CLI입니다. 코드를 고치기 전에 사람이나 AI 코딩 에이전트가 **"이건 무엇과 닿아 있고, 바꾸면 무엇이 깨지는가?"** 를 물어볼 수 있습니다.
8
+
9
+ > **상태: 초기 개발 단계.**
10
+ > 무료 로컬 기능은 처음부터 끝까지 동작합니다. 저장소를 인덱싱하고(`atlas index`), 파일에 대한 브리핑을 받고(`atlas context`), 변경의 영향 범위를 추적하고(`atlas impact`), 그림으로 그리고(`atlas mermaid`), 에이전트가 같은 질문을 MCP로 하게 할 수 있습니다(`atlas mcp`).
11
+ > npm에 [`repo-atlas-cli`](https://www.npmjs.com/package/repo-atlas-cli)로 배포되어 있습니다. 유료 플랜은 계획 단계입니다.
12
+
13
+ **바로가기:** [빠른 시작](#빠른-시작) · [사용법](#사용법) · [AI 에이전트에서 쓰기](#ai-에이전트에서-쓰기) · [설치](#설치)
14
+
15
+ ## 개요
16
+
17
+ 코딩 에이전트는 눈앞의 파일만 봐서는 보이지 않는 관계를 놓칠 때 엉뚱한 파일을 고칩니다. Python 작업도 같이 읽는 테이블, 모듈 세 곳이 의존하는 환경변수 키, 배럴 파일을 거쳐 다시 내보내지는 함수, 지금 바꾸는 코드를 설명하는 문서 같은 것들입니다.
18
+
19
+ Repo Atlas는 이런 관계를 질의할 수 있는 그래프 하나에 모아 둡니다.
20
+
21
+ 1. tree-sitter로 저장소를 파싱해 파일마다 import, 함수, 호출, SQL 테이블, 환경변수 키, 문서 참조를 기록합니다.
22
+ 2. 이 사실들을 그래프로 연결해 로컬 SQLite 파일(`.atlas/graph.db`)에 저장합니다.
23
+ 3. CLI와 MCP 서버가 그래프에서 답합니다. 컨텍스트, 영향 범위, 경로, 다이어그램.
24
+
25
+ 큰 코드베이스를 유지하는 팀과 AI 코딩 에이전트로 일하는 사람을 위해 만들었습니다.
26
+
27
+ ### 실제 화면
28
+
29
+ 아래 그림은 모두 실제 출력이며, 이 저장소에 들어 있는 작은 샘플 저장소 `fixtures/shop`(TypeScript, TSX, Python, SQL, Markdown)에서 캡처했습니다. 손댄 곳은 하나입니다. 긴 폴더 경로를 `~/shop`으로 줄였습니다.
30
+
31
+ **저장소 인덱싱** (Phase 1, 2). 두 번째 실행에서는 바뀐 파일이 없어서 아무것도 다시 파싱하지 않습니다.
32
+
33
+ <img src="assets/index.png" alt="터미널: atlas index가 파일 13개를 노드 35개와 엣지 66개로 파싱하고, 두 번째 실행은 0개를 파싱하며, atlas stats가 노드·엣지·언어·가장 많이 의존되는 파일을 보여 준다" width="720">
34
+
35
+ **파일을 고치기 전 브리핑** (Phase 3). 무엇을 정의하고 쓰는지, 누가 이 파일을 쓰는지, 어떤 테이블을 건드리는지, 어떤 문서가 언급하는지 보여 줍니다.
36
+
37
+ <img src="assets/context.png" alt="터미널: src/users/repo.ts에 대한 atlas context. 함수, import, 호출, 읽고 쓰는 users 테이블, import하는 파일 4개, 호출자 3개, 문서 1개가 나온다" width="820">
38
+
39
+ **변경이 깨뜨릴 수 있는 것, 그리고 둘이 이어진 이유** (Phase 3). `users` 테이블은 TypeScript와 Python 스크립트 양쪽에서 읽히고, React 컴포넌트는 import 두 번을 거쳐 이 테이블에 닿습니다.
40
+
41
+ <img src="assets/impact.png" alt="터미널: users 테이블에 대한 atlas impact가 거리별로 묶여 나오고, web/App.tsx에서 users 테이블까지의 atlas path가 나온다" width="720">
42
+
43
+ **함수 하나의 주변을 다이어그램으로** (`atlas mermaid --focus findUser`). GitHub이 바로 렌더링합니다.
44
+
45
+ ```mermaid
46
+ flowchart LR
47
+ n0["docs/architecture.md"]
48
+ n1["src/users/repo.ts"]
49
+ n2("handleOrder")
50
+ n3("query")
51
+ n4("OrderService.place")
52
+ n5("findUser")
53
+ n6("OrderList")
54
+ n0 -->|documents| n5
55
+ n1 -->|defines| n5
56
+ n2 -->|calls| n5
57
+ n4 -->|calls| n5
58
+ n5 -->|calls| n3
59
+ n6 -->|calls| n5
60
+ style n5 stroke-width:3px
61
+ ```
62
+
63
+ **같은 그래프를 코딩 에이전트에게** (Phase 4). Model Context Protocol로 제공합니다.
64
+
65
+ <img src="assets/mcp.png" alt="터미널: atlas init이 MCP 서버를 등록하고, 서버가 도구 6개를 나열하며, atlas_path 호출이 web/App.tsx에서 users 테이블까지의 연결을 돌려준다" width="820">
66
+
67
+ **규칙은 지시문이 아니라 도구가 지킵니다** (Phase 0). 잘못된 레이어에서 SQLite에 손을 대는 편집은 대신 무엇을 해야 하는지와 함께 곧바로 에이전트에게 되돌아갑니다.
68
+
69
+ <img src="assets/hook.png" alt="터미널: PostToolUse 훅이 src/query/shortcut.ts를 린트 오류 3건과 종료 코드 2로 거부한다" width="820">
70
+
71
+ ## 기능
72
+
73
+ | 기능 | 상태 |
74
+ |---|---|
75
+ | `atlas index`: TypeScript, TSX, JavaScript, Python을 tree-sitter로 추출 | 완료 |
76
+ | SQL 테이블: `.sql` 파일과 문자열 리터럴 안의 SQL을 정의 / 읽기 / 쓰기로 구분 | 완료 |
77
+ | 환경변수 키: `process.env.X`, `import.meta.env.X`, `os.environ`, `os.getenv`, 그리고 `.env.example`에 선언된 키 | 완료 |
78
+ | 문서: 파일, 함수, 테이블, 환경변수 키를 가리키는 Markdown 링크와 백틱 이름 | 완료 |
79
+ | import 해석: 상대 경로, `.js`→`.ts`, index 파일, tsconfig `paths` / `baseUrl`, 워크스페이스 패키지 이름, Python 패키지와 상대 import | 완료 |
80
+ | 호출 해석: named·default·namespace import, 배럴 re-export, `this` / `self`, JSX 컴포넌트 | 완료 |
81
+ | 증분 인덱싱: 바뀐 파일만 다시 파싱하고, 모든 질의가 먼저 인덱스를 갱신 | 완료 |
82
+ | `atlas context` / `impact` / `path` / `search` / `stats` / `export`, 모두 `--json` 지원 | 완료 |
83
+ | `atlas mermaid`: 파일 단위 전체 그림 또는 노드 하나의 주변 | 완료 |
84
+ | `atlas mcp`: 도구 6개를 가진 MCP 서버(stdio). `atlas init`이 `.mcp.json`에 등록 | 완료 |
85
+ | 로컬 SQLite 인덱스(내장 `node:sqlite`, 컴파일할 것 없음) | 완료 |
86
+ | npm 패키지 배포 (`repo-atlas-cli`) | 완료 |
87
+ | 언어 추가(Go, Rust, Java, Ruby: 문법 파일은 의존성에 이미 포함) | 예정 |
88
+ | IDE 연동 | 예정 |
89
+ | 유료 플랜: private 저장소 호스티드 인덱싱, 팀 공유 그래프, CI 연동 | 계획중 |
90
+
91
+ ### 동작 방식
92
+
93
+ - **추출**: 파일을 하나씩 따로 파싱해 단순한 사실(심볼, import, 호출, 테이블, 환경변수 키, 문서 참조)로 만듭니다. 한 파일의 사실은 그 파일에만 의존하므로, 바뀌지 않은 파일은 다시 파싱하지 않습니다.
94
+ - **연결**: 모든 파일의 사실을 노드(`file`, `symbol`, `table`, `env`, `module`)와 엣지(`imports`, `defines`, `calls`, `defines_table`, `reads_table`, `writes_table`, `uses_env`, `declares_env`, `documents`)로 잇습니다. 연결은 순수 함수이며 속성 기반 테스트로 검증합니다. 끊어진 엣지가 없고, 중복이 없고, 파일 순서와 무관하게 결과가 같습니다.
95
+ - **저장**: 사실과 그래프는 저장소 안의 `.atlas/graph.db`에, **사용자의 컴퓨터에만** 있습니다. 이 폴더는 스스로를 git에서 제외합니다. 컴퓨터 밖으로 나가는 것은 없습니다.
96
+ - **질의**: `impact`는 의존 엣지를 거꾸로 따라갑니다. 함수를 거치는 경로는 정밀하게(호출자의 호출자까지) 따라가고, import로 닿은 파일은 그 파일을 import하는 쪽으로 계속 따라갑니다.
97
+ - **AI를 쓰지 않습니다**: 그래프는 모델이 아니라 파싱으로 만듭니다. API 키가 필요 없고 네트워크 요청도 하지 않습니다.
98
+
99
+ ### 인덱싱 대상
100
+
101
+ | 종류 | 파일 | 기록하는 것 |
102
+ |---|---|---|
103
+ | TypeScript / JavaScript | `.ts` `.tsx` `.mts` `.cts` `.js` `.jsx` `.mjs` `.cjs` | 최상위 함수, 클래스, 메서드. import, re-export, `require`, 동적 `import()`. 호출, `new`, JSX 컴포넌트 |
104
+ | Python | `.py` | 함수, 클래스, 메서드. `import` / `from … import`. 호출. `__tablename__` |
105
+ | SQL | `.sql`, 코드 문자열 안의 SQL | `CREATE` / `ALTER` / `INSERT` / `UPDATE` / `DELETE` / `FROM` / `JOIN` / `REFERENCES`, 그리고 `.from("table")` 쿼리 빌더 |
106
+ | 설정 | `.env.example`, `.env.sample`, `.env.template` | 키 이름만 읽고 값은 읽지 않습니다. 실제 `.env` 파일은 열지 않습니다. |
107
+ | 문서 | `.md` `.mdx` | 상대 링크와 `` `백틱` `` 이름 |
108
+
109
+ git 저장소 안에서는 파일 목록을 git에서 받으므로 `.gitignore`를 따르고, 커밋된 `build/`나 `vendor/` 폴더도 다른 소스처럼 인덱싱합니다(`node_modules`는 항상 제외). 그 밖에서는 흔한 산출물 폴더(`node_modules`, `dist`, `.venv` 등)를 건너뜁니다. 1 MiB가 넘는 파일은 건너뜁니다.
110
+
111
+ ## 요구 사항
112
+
113
+ - Node.js **22.13 이상** (Node 24에서 개발). 내장 SQLite 모듈에 필요합니다.
114
+ - [pnpm](https://pnpm.io) 10 (소스에서 빌드할 때만)
115
+ - Git (선택. 파일 목록과 저장소 루트를 찾는 데 씁니다)
116
+
117
+ ## 설치
118
+
119
+ ```bash
120
+ npm install -g repo-atlas-cli
121
+ atlas --version
122
+ ```
123
+
124
+ 패키지 이름은 `repo-atlas-cli`이고, 설치되는 명령은 `atlas`입니다. 설치 없이 써 보려면 `npx repo-atlas-cli index`를 실행합니다.
125
+
126
+ 소스에서 빌드하려면 다음과 같이 합니다.
127
+
128
+ ```bash
129
+ git clone https://github.com/Trapa-Eureka/repo-atlas.git
130
+ cd repo-atlas
131
+ pnpm install
132
+ pnpm build
133
+ alias atlas='node /path/to/repo-atlas/dist/cli/main.js' # 경로는 맞게 바꿉니다
134
+ ```
135
+
136
+ ## 빠른 시작
137
+
138
+ [설치](#설치)의 빌드와 `atlas` alias가 필요합니다. 그다음 아무 저장소에서나:
139
+
140
+ 1. **인덱싱합니다.** `cd your-project` 후 `atlas index`. `.atlas/` 폴더가 생깁니다(스스로 git에서 제외되며 내 컴퓨터에만 있습니다).
141
+ 2. **고치기 전에 물어봅니다.** `atlas context src/some/file.ts`는 그 파일이 무엇을 정의하고 쓰는지, 누가 쓰는지, 어떤 테이블과 환경변수 키를 건드리는지, 어떤 문서가 언급하는지 보여 줍니다.
142
+ 3. **영향 범위를 확인합니다.** `atlas impact <파일 | 함수 | 테이블 | ENV_KEY>`는 거기에 의존하는 모든 것을 나열합니다.
143
+ 4. **에이전트에게 줍니다.** `atlas init`이 MCP 서버를 `.mcp.json`에 등록합니다. 에이전트를 다시 시작하세요. [AI 에이전트에서 쓰기](#ai-에이전트에서-쓰기)를 보세요.
144
+
145
+ `atlas index`를 다시 실행할 필요는 없습니다. 모든 명령이 먼저 지난 실행 이후 바뀐 파일을 다시 파싱합니다.
146
+
147
+ ## 사용법
148
+
149
+ 모든 명령은 `-C <dir>`(다른 저장소에서 작업), `--json`(기계가 읽는 출력), `--no-refresh`(변경 확인 없이 저장된 인덱스로 답하기)를 받습니다.
150
+
151
+ | 하고 싶은 일 | 명령 |
152
+ |---|---|
153
+ | 인덱스를 만들거나 갱신 | `atlas index [dir]` (`--full`은 전부 다시 파싱) |
154
+ | 이름으로 노드 찾기 | `atlas search <query> [--kind file\|symbol\|table\|env\|module] [--limit n]` |
155
+ | 모든 테이블(또는 환경변수 키) 나열 | `atlas search "" --kind table` |
156
+ | 고치기 전 브리핑 받기 | `atlas context <target>` |
157
+ | 변경이 깨뜨릴 수 있는 것 보기 | `atlas impact <target> [--depth n]` |
158
+ | 두 대상이 어떻게 이어지는지 보기 | `atlas path <from> <to>` |
159
+ | 파일 단위 전체 그림 그리기 | `atlas mermaid [--max n] [-o graph.mmd]` |
160
+ | 노드 하나의 주변 그리기 | `atlas mermaid --focus <target> [--depth n]` |
161
+ | 그래프 크기, 허브 파일, 해석 못 한 import 보기 | `atlas stats [--unresolved]` |
162
+ | 그래프 전체 내보내기 | `atlas export [-o graph.json]` |
163
+
164
+ ### 대상(target) 지정
165
+
166
+ `<target>`에는 다음을 쓸 수 있습니다.
167
+
168
+ - 파일 경로. 저장소 루트 기준이든 현재 위치 기준이든 됩니다: `src/users/repo.ts`, 또는 뒷부분만 `users/repo.ts`
169
+ - 함수, 클래스, 메서드 이름: `findUser`, `OrderService.place`
170
+ - 특정 파일의 심볼: `src/users/repo.ts#findUser`
171
+ - 테이블, 환경변수 키, 패키지 이름: `users`, `DATABASE_URL`, `react`
172
+ - 다른 명령이 출력한 노드 id: `sym:src/users/repo.ts#findUser`, `table:users`
173
+
174
+ 이름이 노드 여러 개와 맞으면 후보를 출력하고 종료 코드 `2`로 끝납니다. id 중 하나를 고르세요. 그 밖의 오류는 `1`로 끝납니다.
175
+
176
+ ### `impact` 읽는 법
177
+
178
+ 각 줄 끝에는 그 노드가 나온 이유가 붙습니다: `[calls X]`, `[imports X]`, `[reads_table X]`, `[documents X]`. `[contains X]`는 영향받는 함수가 들어 있는 파일이라는 표시입니다. 영향받는 노드를 언급하는 문서는 고칠 수 있도록 나열하지만, 그 문서에서 더 따라가지는 않습니다.
179
+
180
+ ### 이 저장소 개발하기
181
+
182
+ ```bash
183
+ pnpm check # 타입체크 + 린트 + 테스트 + 훅 테스트: 변경이 통과해야 하는 것
184
+ pnpm build # dist/ 로 컴파일
185
+ pnpm test # 추출기, 링커(속성 기반), CLI, MCP 테스트
186
+ pnpm test:hooks # 개발용 훅 테스트
187
+ ```
188
+
189
+ ## AI 에이전트에서 쓰기
190
+
191
+ `atlas mcp`는 stdin/stdout으로 [Model Context Protocol](https://modelcontextprotocol.io) 서버를 실행합니다. 저장소마다 한 번 등록합니다.
192
+
193
+ ```bash
194
+ atlas init # .mcp.json에 "repo-atlas"를 추가하고 다른 서버는 그대로 둡니다
195
+ ```
196
+
197
+ 직접 적어도 됩니다.
198
+
199
+ ```json
200
+ {
201
+ "mcpServers": {
202
+ "repo-atlas": { "command": "atlas", "args": ["mcp"] }
203
+ }
204
+ }
205
+ ```
206
+
207
+ `atlas` 명령이 에이전트의 `PATH`에 있어야 합니다. 소스에서 실행할 때는 `"command": "atlas", "args": ["mcp"]`를 `"command": "node", "args": ["/path/to/repo-atlas/dist/cli/main.js", "mcp"]`로 바꾸세요.
208
+
209
+ | 도구 | 답하는 질문 |
210
+ |---|---|
211
+ | `atlas_search` | 이 이름을 가진 노드는? |
212
+ | `atlas_context` | 이걸 고치기 전에 무엇을 알아야 하나? |
213
+ | `atlas_impact` | 무엇이 여기에 의존하고, 어떤 문서가 언급하나? |
214
+ | `atlas_path` | 이 둘은 어떻게 이어져 있나? |
215
+ | `atlas_mermaid` | 그래프의 이 부분을 그려 줘 |
216
+ | `atlas_stats` | 그래프 크기, 허브 파일, 해석 못 한 import는? |
217
+
218
+ 도구 호출마다 먼저 바뀐 파일을 다시 인덱싱하므로, 답은 에이전트가 고치고 있는 작업 트리와 일치합니다. MCP가 없는 에이전트는 CLI를 `--json`으로 호출하면 됩니다.
219
+
220
+ ## 알려진 한계
221
+
222
+ - **호출은 타입이 아니라 이름과 import로 해석합니다.** 인스턴스에서 부르는 메서드(`const s = new Service(); s.run()`), 체이닝 호출(`a.b().c()`), 동적 디스패치는 따라가지 않습니다. 해석할 수 없는 호출은 추측하지 않고 뺍니다. 그래서 그래프는 엣지를 지어내는 대신 놓치는 쪽입니다.
223
+ - **SQL 탐지는 패턴 기반입니다.** SQL 텍스트를 읽습니다. 문자열을 이어 붙여 만든 쿼리나 ORM(Prisma, Drizzle, SQLAlchemy 표현식)이 만든 쿼리는 보지 못합니다. 인스턴스에서 부르는 `.from("name")` 호출은 테이블 읽기로 보는데, 쿼리 빌더가 아닌 라이브러리라면 틀릴 수 있습니다. 파일 어디에서든 CTE로 정의된 이름(`WITH recent AS (...)`)은 그 파일에서 테이블로 치지 않습니다. 코드가 CTE를 한 문자열에서 정의하고 다른 문자열에서 읽는 일이 흔하기 때문인데, 같은 이름의 실제 테이블이 있으면 그 파일에서의 읽기는 빠집니다.
224
+ - tsconfig의 `extends`는 따라가지 않고, `package.json`의 `exports` 맵은 읽지 않습니다. 워크스페이스 패키지는 `src/index`, `index`, 또는 `main` 파일로 해석합니다.
225
+ - Python 절대 import는 저장소 루트에서 먼저 찾고, 없으면 유일한 경로 접미사로 찾습니다. 모듈 경로가 같은 패키지가 둘이면 해석하지 않습니다.
226
+ - 문서는 상대 링크와 백틱 이름으로만 연결합니다. 백틱 안의 흔한 단어가 마침 그 이름을 가진 유일한 함수라면 연결됩니다. 가장 덜 믿을 만한 엣지 종류입니다(아래 수치 참고).
227
+ - 환경변수 키는 소스 텍스트에서 찾으므로, 문자열이나 주석 안에 적힌 키도 사용으로 칩니다.
228
+ - 최상위 함수, 클래스, 그 메서드만 심볼입니다. 중첩 함수는 그것을 감싼 함수의 것으로 칩니다.
229
+ - **측정한 정확도는 표본이지 증명이 아닙니다.** 공개 저장소 10개를 인덱싱했습니다(express, flask, httpx, got, swr, hono, datasette, full-stack-fastapi-template, umami, trpc: 파일 4,903개, 관계 약 54,000개. 가장 큰 1,741개 파일 저장소가 1.6초). 무작위로 뽑은 엣지 180개를 소스와 직접 대조했습니다: 호출 40/40, import 30/30, 테이블 엣지 40/40, env 엣지 29/30, 문서 엣지 38/40. 로컬 import 약 12,000개 중 70개가 해석되지 않았고, 그중 67개는 저장소에 없는 파일(생성된 클라이언트, 빌드 산출물)을 가리킵니다. 이 수치는 잘못된 엣지만 잰 것입니다. 빠진 엣지는 세지 않았고, 위 첫 번째 한계 때문에 빠진 엣지는 많습니다.
230
+ - macOS에서 개발했습니다. Linux는 동작할 것으로 보이고 Windows는 테스트하지 않았습니다. Node 내장 SQLite는 아직 Node에서 실험 기능으로 표시되어 있으며, `atlas`는 그 시작 경고를 숨깁니다.
231
+
232
+ ## 유료 플랜 (계획중)
233
+
234
+ 내 컴퓨터에서 도는 것은 모두 무료이고 앞으로도 무료입니다. 인덱싱, 모든 질의, 다이어그램, MCP 서버가 여기에 들어갑니다. 서버가 필요한 기능(private 저장소 호스티드 인덱싱, 팀이 함께 보는 그래프, CI 연동)의 유료 플랜은 계획 단계입니다. 아직 판매하는 것은 없고, 가격과 세부 사항도 정해지지 않았습니다.
235
+
236
+ ## 에이전트 하네스
237
+
238
+ 이 저장소는 AI 코딩 에이전트와 함께 개발하며, 규칙은 긴 지시 파일이 아니라 도구로 강제합니다.
239
+
240
+ - **`CLAUDE.md`는 짧습니다.** 코드만 봐서는 에이전트가 알 수 없는 것만 담습니다.
241
+ - **아키텍처는 린트 규칙이 지킵니다** (`eslint.config.js`). 어느 레이어가 어느 레이어를 import할 수 있는지, 그리고 SQLite·tree-sitter·인자 파서·MCP SDK는 각각 한 레이어만 만질 수 있다는 규칙입니다. 메시지마다 대신 무엇을 해야 하는지 적혀 있습니다.
242
+ - **훅** (`.claude/settings.json`, 스크립트와 테스트는 `.claude/hooks/`):
243
+ - `PreToolUse`는 되돌리기 어려운 동작을 막습니다. 넓은 범위의 재귀 삭제, 강제 푸시, `reset --hard`, 비밀·인덱스 파일 스테이징, 파괴적 SQL, `curl | sh`, `npm publish`, 키 모양 문자열을 파일에 쓰는 것.
244
+ - `PostToolUse`는 방금 고친 파일을 린트하고 위반을 에이전트에게 돌려보냅니다(종료 코드 2).
245
+ - `Stop`은 코드가 바뀌었으면 타입체크와 테스트를 돌리고, 실패한 채로는 턴이 끝나지 않게 합니다.
246
+ - **거부(deny) 규칙**은 실제 env 파일을 읽지 못하게 하고, 배포는 사람 손에 둡니다.
247
+ - **스킬** (`.claude/skills/`)에는 가끔만 필요한 절차가 있습니다. 언어 추가, 그리고 실제 CLI 출력으로 변경을 증명하는 방법.
248
+ - **새 눈의 리뷰어** (`.claude/agents/fresh-reviewer.md`)는 변경이 어떻게 작성됐는지 보지 않은 상태에서 리뷰합니다.
249
+
250
+ 훅은 안전망이지 완전한 방어가 아닙니다. 명령 텍스트를 맞춰 보는 방식이라, 감싸거나 난독화한 명령은 빠져나갈 수 있고, 위험해 보이는 문자열이 들어 있을 뿐인 무해한 명령이 막힐 수 있습니다.
251
+
252
+ ## 데이터와 프라이버시
253
+
254
+ - 인덱스(`.atlas/`)는 내 컴퓨터에 남습니다. 폴더 안에 자체 `.gitignore`가 있어 실수로 커밋되지 않습니다.
255
+ - 인덱스에는 파일 경로, 심볼 이름, 테이블 이름, 환경변수 키 **이름**이 들어갑니다. 파일 내용이나 환경변수 값은 들어가지 않습니다.
256
+ - 실제 env 파일(`.env`, `.env.local` 등)은 열지 않습니다. `.env.example` 같은 템플릿만 읽습니다.
257
+ - 텔레메트리도, 네트워크 요청도, API 키도 없습니다.
258
+
259
+ ## 프로젝트 구조
260
+
261
+ ```
262
+ repo-atlas/
263
+ ├── src/
264
+ │ ├── graph/ # 노드·엣지 타입, 메모리 내 그래프
265
+ │ ├── extract/ # 파일 하나 -> 사실 (tree-sitter, SQL, env, Markdown)
266
+ │ ├── indexer/ # 파일 목록, import 별칭, 사실을 그래프로 연결, 증분 인덱싱
267
+ │ ├── store/ # SQLite (SQL을 아는 유일한 모듈)
268
+ │ ├── query/ # search, context, impact, path, mermaid, stats (메모리 내 그래프 위의 순수 함수)
269
+ │ ├── app/ # Atlas: CLI와 MCP 서버가 함께 부르는 것
270
+ │ ├── mcp/ # MCP 서버
271
+ │ └── cli/ # `atlas` 명령
272
+ ├── test/ # 추출기, 링커(속성 기반), CLI, MCP 테스트
273
+ ├── fixtures/shop/ # 테스트가 인덱싱하는 샘플 저장소
274
+ ├── assets/ # README 스크린샷과 소셜 프리뷰 이미지
275
+ ├── scripts/ # assets/ 이미지를 다시 만드는 스크립트 (`pnpm screenshots`)
276
+ ├── .claude/
277
+ │ ├── settings.json
278
+ │ ├── hooks/ # 개발용 훅과 테스트
279
+ │ ├── skills/ # add-language, verify-change
280
+ │ └── agents/ # fresh-reviewer
281
+ ├── CLAUDE.md # 이 저장소에서 일하는 AI 에이전트를 위한 짧은 안내
282
+ └── eslint.config.js # 레이어 경계
283
+ ```
284
+
285
+ ### 기술 스택
286
+
287
+ TypeScript(ESM), Node.js 22+ · 미리 빌드된 WASM 문법을 쓰는 [web-tree-sitter](https://github.com/tree-sitter/tree-sitter)(네이티브 빌드 없음) · 내장 `node:sqlite` · [commander](https://github.com/tj/commander.js) · [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) · Vitest와 [fast-check](https://github.com/dubzzz/fast-check) · ESLint · pnpm
288
+
289
+ ## 로드맵
290
+
291
+ - [x] **Phase 0**: 하네스: 짧은 `CLAUDE.md`, 훅, 린트로 강제하는 레이어, 샘플 저장소
292
+ - [x] **Phase 1**: 추출: TypeScript / JavaScript / Python, SQL, 환경변수 키, Markdown
293
+ - [x] **Phase 2**: 그래프: 연결, SQLite 저장소, 증분 인덱싱
294
+ - [x] **Phase 3**: 질의와 CLI: `search`, `context`, `impact`, `path`, `mermaid`, `stats`, `export`
295
+ - [x] **Phase 4**: 에이전트: MCP 서버, `atlas init`
296
+ - [ ] **Phase 5**: 릴리스
297
+ - [x] npm 패키지 ([`repo-atlas-cli`](https://www.npmjs.com/package/repo-atlas-cli))
298
+ - [ ] 언어 추가
299
+ - [ ] IDE 연동
300
+ - [ ] **Phase 6**: 유료 플랜: private 저장소 호스티드 인덱싱, 팀 공유 그래프, CI 연동 (계획중)
301
+
302
+ ## 기여
303
+
304
+ 프로젝트는 초기 단계입니다. 풀 리퀘스트를 보내기 전에 이슈를 열어 변경 내용을 먼저 논의해 주세요. 이 저장소의 파일은 모두 영어로 작성하며, 이 문서만 한국어 번역입니다.
305
+
306
+ ## 라이선스
307
+
308
+ [MIT](LICENSE).