repo-atlas-cli 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.ko.md +305 -0
- package/README.md +302 -2
- package/dist/app/atlas.d.ts +52 -0
- package/dist/app/atlas.js +99 -0
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +11 -0
- package/dist/cli/program.d.ts +4 -0
- package/dist/cli/program.js +175 -0
- package/dist/cli/render.d.ts +16 -0
- package/dist/cli/render.js +85 -0
- package/dist/extract/code.d.ts +4 -0
- package/dist/extract/code.js +283 -0
- package/dist/extract/facts.d.ts +57 -0
- package/dist/extract/facts.js +3 -0
- package/dist/extract/index.d.ts +7 -0
- package/dist/extract/index.js +86 -0
- package/dist/extract/parser.d.ts +3 -0
- package/dist/extract/parser.js +21 -0
- package/dist/extract/sql.d.ts +12 -0
- package/dist/extract/sql.js +86 -0
- package/dist/extract/text.d.ts +5 -0
- package/dist/extract/text.js +74 -0
- package/dist/graph/graph.d.ts +12 -0
- package/dist/graph/graph.js +41 -0
- package/dist/graph/types.d.ts +23 -0
- package/dist/graph/types.js +17 -0
- package/dist/indexer/aliases.d.ts +5 -0
- package/dist/indexer/aliases.js +104 -0
- package/dist/indexer/indexer.d.ts +27 -0
- package/dist/indexer/indexer.js +118 -0
- package/dist/indexer/link.d.ts +27 -0
- package/dist/indexer/link.js +340 -0
- package/dist/indexer/walk.d.ts +14 -0
- package/dist/indexer/walk.js +80 -0
- package/dist/mcp/server.d.ts +8 -0
- package/dist/mcp/server.js +69 -0
- package/dist/query/context.d.ts +30 -0
- package/dist/query/context.js +68 -0
- package/dist/query/impact.d.ts +28 -0
- package/dist/query/impact.js +63 -0
- package/dist/query/mermaid.d.ts +17 -0
- package/dist/query/mermaid.js +77 -0
- package/dist/query/path.d.ts +11 -0
- package/dist/query/path.js +32 -0
- package/dist/query/resolve.d.ts +17 -0
- package/dist/query/resolve.js +81 -0
- package/dist/query/stats.d.ts +14 -0
- package/dist/query/stats.js +22 -0
- package/dist/store/store.d.ts +27 -0
- package/dist/store/store.js +88 -0
- 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,305 @@
|
|
|
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**: 릴리스: npm 패키지(완료: `repo-atlas-cli`), 언어 추가, IDE 연동
|
|
297
|
+
- [ ] **Phase 6**: 유료 플랜: private 저장소 호스티드 인덱싱, 팀 공유 그래프, CI 연동 (계획중)
|
|
298
|
+
|
|
299
|
+
## 기여
|
|
300
|
+
|
|
301
|
+
프로젝트는 초기 단계입니다. 풀 리퀘스트를 보내기 전에 이슈를 열어 변경 내용을 먼저 논의해 주세요. 이 저장소의 파일은 모두 영어로 작성하며, 이 문서만 한국어 번역입니다.
|
|
302
|
+
|
|
303
|
+
## 라이선스
|
|
304
|
+
|
|
305
|
+
[MIT](LICENSE).
|
package/README.md
CHANGED
|
@@ -1,3 +1,303 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Repo Atlas
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** · [KOREAN](README.ko.md)
|
|
4
|
+
|
|
5
|
+
A local CLI that maps how the files, functions, SQL tables, env keys and docs of a repository relate, so that you or an AI coding agent can ask **"what does this touch, and what breaks if I change it?"** before editing.
|
|
6
|
+
|
|
7
|
+
> **Status: early development.**
|
|
8
|
+
> The free, local tier works end to end: index a repository (`atlas index`), ask for a briefing on a file (`atlas context`), trace what a change affects (`atlas impact`), draw the result (`atlas mermaid`), and let an agent ask the same questions over MCP (`atlas mcp`).
|
|
9
|
+
> It is on npm as [`repo-atlas-cli`](https://www.npmjs.com/package/repo-atlas-cli). Paid plans are still in planning.
|
|
10
|
+
|
|
11
|
+
**Jump to:** [Quick start](#quick-start) · [Usage](#usage) · [Use it from an AI agent](#use-it-from-an-ai-agent) · [Installation](#installation)
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
Coding agents edit the wrong file when they miss a relation that is not visible from the file in front of them: a table that a Python job also reads, an env key three modules depend on, a function re-exported through a barrel file, a doc that describes the code being changed.
|
|
16
|
+
|
|
17
|
+
Repo Atlas keeps those relations in one queryable graph:
|
|
18
|
+
|
|
19
|
+
1. It parses the repository with tree-sitter and records, per file, the imports, functions, calls, SQL tables, env keys and doc references.
|
|
20
|
+
2. It links those facts into a graph stored in a local SQLite file (`.atlas/graph.db`).
|
|
21
|
+
3. The CLI and an MCP server answer questions from the graph: context, impact, path, diagram.
|
|
22
|
+
|
|
23
|
+
It is built for teams that maintain a large codebase and for people who work with AI coding agents.
|
|
24
|
+
|
|
25
|
+
### What it looks like
|
|
26
|
+
|
|
27
|
+
Every picture below is real output, captured from `fixtures/shop`, the small sample repository in this repo (TypeScript, TSX, Python, SQL, Markdown). The only edit: the long folder path was shortened to `~/shop`.
|
|
28
|
+
|
|
29
|
+
**Index a repository** (Phases 1 and 2). The second run parses nothing, because no file changed:
|
|
30
|
+
|
|
31
|
+
<img src="assets/index.png" alt="Terminal: atlas index parses 13 files into 35 nodes and 66 edges, a second run parses 0 files, and atlas stats lists nodes, edges, languages and the most depended-on files" width="720">
|
|
32
|
+
|
|
33
|
+
**A briefing before editing a file** (Phase 3). What it defines and uses, who uses it, the tables it touches, the docs that mention it:
|
|
34
|
+
|
|
35
|
+
<img src="assets/context.png" alt="Terminal: atlas context for src/users/repo.ts, listing its functions, imports, calls, the users table it reads and writes, four importing files, three callers and one doc" width="820">
|
|
36
|
+
|
|
37
|
+
**What a change can break, and why two things are connected** (Phase 3). The `users` table is read from TypeScript and from a Python script, and a React component reaches it through two imports:
|
|
38
|
+
|
|
39
|
+
<img src="assets/impact.png" alt="Terminal: atlas impact for the users table grouped by distance, and atlas path from web/App.tsx to the users table" width="720">
|
|
40
|
+
|
|
41
|
+
**The neighbourhood of one function as a diagram** (`atlas mermaid --focus findUser`), which GitHub renders directly:
|
|
42
|
+
|
|
43
|
+
```mermaid
|
|
44
|
+
flowchart LR
|
|
45
|
+
n0["docs/architecture.md"]
|
|
46
|
+
n1["src/users/repo.ts"]
|
|
47
|
+
n2("handleOrder")
|
|
48
|
+
n3("query")
|
|
49
|
+
n4("OrderService.place")
|
|
50
|
+
n5("findUser")
|
|
51
|
+
n6("OrderList")
|
|
52
|
+
n0 -->|documents| n5
|
|
53
|
+
n1 -->|defines| n5
|
|
54
|
+
n2 -->|calls| n5
|
|
55
|
+
n4 -->|calls| n5
|
|
56
|
+
n5 -->|calls| n3
|
|
57
|
+
n6 -->|calls| n5
|
|
58
|
+
style n5 stroke-width:3px
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**The same graph for a coding agent** (Phase 4), over the Model Context Protocol:
|
|
62
|
+
|
|
63
|
+
<img src="assets/mcp.png" alt="Terminal: atlas init registers the MCP server, the server lists six tools, and a call to atlas_path returns the chain from web/App.tsx to the users table" width="820">
|
|
64
|
+
|
|
65
|
+
**Rules enforced by tools, not by instructions** (Phase 0). An edit that reaches into SQLite from the wrong layer is sent straight back to the agent, with what to do instead:
|
|
66
|
+
|
|
67
|
+
<img src="assets/hook.png" alt="Terminal: the PostToolUse hook rejects src/query/shortcut.ts with three lint errors and exit code 2" width="820">
|
|
68
|
+
|
|
69
|
+
## Features
|
|
70
|
+
|
|
71
|
+
| Feature | Status |
|
|
72
|
+
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
73
|
+
| `atlas index`: tree-sitter extraction for TypeScript, TSX, JavaScript and Python | Done |
|
|
74
|
+
| SQL tables: `.sql` files and SQL inside string literals, split into defined / read / written | Done |
|
|
75
|
+
| Env keys: `process.env.X`, `import.meta.env.X`, `os.environ`, `os.getenv`, and keys declared in `.env.example` | Done |
|
|
76
|
+
| Docs: Markdown links and backticked names that point at files, functions, tables or env keys | Done |
|
|
77
|
+
| Import resolution: relative paths, `.js`→`.ts`, index files, tsconfig `paths` / `baseUrl`, workspace package names, Python packages and relative imports | Done |
|
|
78
|
+
| Call resolution through named, default and namespace imports, barrel re-exports, `this` / `self`, JSX components | Done |
|
|
79
|
+
| Incremental indexing: only changed files are re-parsed; every query refreshes the index first | Done |
|
|
80
|
+
| `atlas context` / `impact` / `path` / `search` / `stats` / `export`, each with `--json` | Done |
|
|
81
|
+
| `atlas mermaid`: file overview or the neighbourhood of one node | Done |
|
|
82
|
+
| `atlas mcp`: MCP server (stdio) with six tools; `atlas init` registers it in `.mcp.json` | Done |
|
|
83
|
+
| Local SQLite index (built-in `node:sqlite`, nothing to compile) | Done |
|
|
84
|
+
| Published npm package (`repo-atlas-cli`) | Done |
|
|
85
|
+
| More languages (Go, Rust, Java, Ruby: the grammars already ship with the dependency) | Planned |
|
|
86
|
+
| IDE integration | Planned |
|
|
87
|
+
| Paid plans: hosted indexing of private repositories, shared team graph, CI integration | Planned |
|
|
88
|
+
|
|
89
|
+
### How it works
|
|
90
|
+
|
|
91
|
+
- **Extract**: each file is parsed on its own into plain facts (symbols, imports, calls, tables, env keys, doc references). Because a file's facts depend on that file only, unchanged files are never re-parsed.
|
|
92
|
+
- **Link**: the facts of all files are joined into nodes (`file`, `symbol`, `table`, `env`, `module`) and edges (`imports`, `defines`, `calls`, `defines_table`, `reads_table`, `writes_table`, `uses_env`, `declares_env`, `documents`). Linking is a pure function, checked with property-based tests: no dangling edges, no duplicates, same result regardless of file order.
|
|
93
|
+
- **Store**: facts and graph live in `.atlas/graph.db` in the repository, on **your own machine**. The folder ignores itself in git. Nothing leaves your computer.
|
|
94
|
+
- **Query**: `impact` walks dependency edges backwards. Paths through functions stay precise (callers of callers); a file reached through an import is followed to its own importers.
|
|
95
|
+
- **No AI inside**: the graph is built by parsing, not by a model. Repo Atlas needs no API key and makes no network requests.
|
|
96
|
+
|
|
97
|
+
### What gets indexed
|
|
98
|
+
|
|
99
|
+
| Kind | Files | What is recorded |
|
|
100
|
+
| ----------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
101
|
+
| TypeScript / JavaScript | `.ts` `.tsx` `.mts` `.cts` `.js` `.jsx` `.mjs` `.cjs` | top-level functions, classes, methods; imports, re-exports, `require`, dynamic `import()`; calls, `new`, JSX components |
|
|
102
|
+
| Python | `.py` | functions, classes, methods; `import` / `from … import`; calls; `__tablename__` |
|
|
103
|
+
| SQL | `.sql`, and SQL in code strings | `CREATE` / `ALTER` / `INSERT` / `UPDATE` / `DELETE` / `FROM` / `JOIN` / `REFERENCES`, plus `.from("table")` query builders |
|
|
104
|
+
| Config | `.env.example`, `.env.sample`, `.env.template` | key names only, never values. Real `.env` files are never opened. |
|
|
105
|
+
| Docs | `.md` `.mdx` | relative links and `` `backticked` `` names |
|
|
106
|
+
|
|
107
|
+
Inside a git repository the file list comes from git, so `.gitignore` is honoured and a committed `build/` or `vendor/` folder is indexed like any other source (`node_modules` never is). Elsewhere, common output folders (`node_modules`, `dist`, `.venv`, …) are skipped. Files over 1 MiB are skipped.
|
|
108
|
+
|
|
109
|
+
## Requirements
|
|
110
|
+
|
|
111
|
+
- Node.js **22.13 or newer** (developed on Node 24). The built-in SQLite module needs it.
|
|
112
|
+
- [pnpm](https://pnpm.io) 10, only to build from source
|
|
113
|
+
- Git (optional; used to list files and to find the repository root)
|
|
114
|
+
|
|
115
|
+
## Installation
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
npm install -g repo-atlas-cli
|
|
119
|
+
atlas --version
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The package is named `repo-atlas-cli`; the command it installs is `atlas`. To try it without installing, use `npx repo-atlas-cli index`.
|
|
123
|
+
|
|
124
|
+
To build from source instead:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
git clone https://github.com/Trapa-Eureka/repo-atlas.git
|
|
128
|
+
cd repo-atlas
|
|
129
|
+
pnpm install
|
|
130
|
+
pnpm build
|
|
131
|
+
alias atlas='node /path/to/repo-atlas/dist/cli/main.js' # adjust the path
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Quick start
|
|
135
|
+
|
|
136
|
+
You need the build from [Installation](#installation) and the `atlas` alias. Then, in any repository:
|
|
137
|
+
|
|
138
|
+
1. **Index it.** `cd your-project`, then `atlas index`. This creates `.atlas/` (git-ignored by itself, on your machine only).
|
|
139
|
+
2. **Ask before you edit.** `atlas context src/some/file.ts` shows what the file defines, what it uses, who uses it, the tables and env keys it touches, and the docs that mention it.
|
|
140
|
+
3. **Check the blast radius.** `atlas impact <file | function | table | ENV_KEY>` lists everything that depends on it.
|
|
141
|
+
4. **Give it to your agent.** `atlas init` registers the MCP server in `.mcp.json`; restart the agent. See [Use it from an AI agent](#use-it-from-an-ai-agent).
|
|
142
|
+
|
|
143
|
+
You do not need to re-run `atlas index`: every command first re-parses the files that changed since the last run.
|
|
144
|
+
|
|
145
|
+
## Usage
|
|
146
|
+
|
|
147
|
+
Every command accepts `-C <dir>` (work on another repository), `--json` (machine-readable output) and `--no-refresh` (answer from the stored index without checking for changes).
|
|
148
|
+
|
|
149
|
+
| I want to... | Command |
|
|
150
|
+
| --------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
151
|
+
| build or update the index | `atlas index [dir]` (`--full` re-parses everything) |
|
|
152
|
+
| find a node by name | `atlas search <query> [--kind file\|symbol\|table\|env\|module] [--limit n]` |
|
|
153
|
+
| list every table (or env key) | `atlas search "" --kind table` |
|
|
154
|
+
| get a briefing before editing something | `atlas context <target>` |
|
|
155
|
+
| see what a change can break | `atlas impact <target> [--depth n]` |
|
|
156
|
+
| understand how two things are connected | `atlas path <from> <to>` |
|
|
157
|
+
| draw the file-level overview | `atlas mermaid [--max n] [-o graph.mmd]` |
|
|
158
|
+
| draw the surroundings of one node | `atlas mermaid --focus <target> [--depth n]` |
|
|
159
|
+
| see graph size, hub files, unresolved imports | `atlas stats [--unresolved]` |
|
|
160
|
+
| dump the whole graph | `atlas export [-o graph.json]` |
|
|
161
|
+
|
|
162
|
+
### Targets
|
|
163
|
+
|
|
164
|
+
A `<target>` can be:
|
|
165
|
+
|
|
166
|
+
- a file path, from the repository root or from where you are: `src/users/repo.ts`, or just its tail `users/repo.ts`
|
|
167
|
+
- a function, class or method name: `findUser`, `OrderService.place`
|
|
168
|
+
- a symbol in a specific file: `src/users/repo.ts#findUser`
|
|
169
|
+
- a table, env key or package name: `users`, `DATABASE_URL`, `react`
|
|
170
|
+
- a node id printed by any command: `sym:src/users/repo.ts#findUser`, `table:users`
|
|
171
|
+
|
|
172
|
+
When a name matches more than one node, the command prints the candidates and exits with code `2`; pick one of the ids. Other errors exit with `1`.
|
|
173
|
+
|
|
174
|
+
### Reading `impact`
|
|
175
|
+
|
|
176
|
+
Each line ends with the reason the node is listed: `[calls X]`, `[imports X]`, `[reads_table X]`, `[documents X]`. `[contains X]` marks the file that holds an affected function. Docs that mention an affected node are listed so you can update them, and are not followed further.
|
|
177
|
+
|
|
178
|
+
### Develop this repository
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
pnpm check # typecheck + lint + tests + hook tests: what a change must pass
|
|
182
|
+
pnpm build # compile to dist/
|
|
183
|
+
pnpm test # extractor, linker (property-based), CLI and MCP tests
|
|
184
|
+
pnpm test:hooks # tests for the dev-time hooks
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## Use it from an AI agent
|
|
188
|
+
|
|
189
|
+
`atlas mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server on stdin/stdout. Register it once per repository:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
atlas init # adds "repo-atlas" to .mcp.json, keeping other servers
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
or add it by hand:
|
|
196
|
+
|
|
197
|
+
```json
|
|
198
|
+
{
|
|
199
|
+
"mcpServers": {
|
|
200
|
+
"repo-atlas": { "command": "atlas", "args": ["mcp"] }
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
The `atlas` command must be on the agent's `PATH`; when running from source, replace `"command": "atlas", "args": ["mcp"]` with `"command": "node", "args": ["/path/to/repo-atlas/dist/cli/main.js", "mcp"]`.
|
|
206
|
+
|
|
207
|
+
| Tool | Answers |
|
|
208
|
+
| --------------- | -------------------------------------------------------------------------- |
|
|
209
|
+
| `atlas_search` | which nodes have this name? |
|
|
210
|
+
| `atlas_context` | what should I know before editing this? |
|
|
211
|
+
| `atlas_impact` | what depends on this, and which docs mention it? |
|
|
212
|
+
| `atlas_path` | how are these two connected? |
|
|
213
|
+
| `atlas_mermaid` | draw this part of the graph |
|
|
214
|
+
| `atlas_stats` | how big is the graph, which files are hubs, which imports did not resolve? |
|
|
215
|
+
|
|
216
|
+
Each tool call first re-indexes changed files, so the answers match the working tree the agent is editing. Agents without MCP can call the CLI with `--json` instead.
|
|
217
|
+
|
|
218
|
+
## Known limitations
|
|
219
|
+
|
|
220
|
+
- **Calls are resolved by name through imports, not by type.** A method called on an instance (`const s = new Service(); s.run()`), a chained call (`a.b().c()`) and dynamic dispatch are not followed. Calls that cannot be resolved are left out instead of guessed, so the graph misses edges rather than inventing them.
|
|
221
|
+
- **SQL detection is pattern-based.** It reads SQL text. Queries built by concatenation or by an ORM (Prisma, Drizzle, SQLAlchemy expressions) are not seen. A `.from("name")` call on an instance is treated as a table read, which can be wrong for a library that is not a query builder. A name defined as a CTE (`WITH recent AS (...)`) anywhere in a file is never counted as a table in that file, because code often defines a CTE in one string and reads it in another; a real table with the same name loses its reads from that file.
|
|
222
|
+
- tsconfig `extends` is not followed, and `package.json` `exports` maps are not read; workspace packages are resolved to `src/index`, `index` or their `main` file.
|
|
223
|
+
- A Python absolute import is matched from the repository root, then by a unique path suffix. Two packages with the same module path are left unresolved.
|
|
224
|
+
- Docs are linked only through relative links and backticked names. A backticked common word that happens to be the only function of that name will be linked; this is the least reliable kind of edge (see the numbers below).
|
|
225
|
+
- Env keys are matched in the source text, so a key named inside a string or a comment counts as a use.
|
|
226
|
+
- Only top-level functions, classes and their methods are symbols. Nested functions are attributed to the function that contains them.
|
|
227
|
+
- **Measured accuracy is a sample, not a proof.** Ten public repositories were indexed (express, flask, httpx, got, swr, hono, datasette, full-stack-fastapi-template, umami, trpc: 4,903 files, about 54,000 relations; the largest, 1,741 files, took 1.6 s). 180 randomly drawn edges were checked by hand against the source: calls 40/40, imports 30/30, table edges 40/40, env edges 29/30, doc edges 38/40. Of roughly 12,000 local imports, 70 were left unresolved; 67 of those point at files that are not in the repository (generated clients, build output). This measures wrong edges only. Missing edges were not counted, and the first limitation above means there are many.
|
|
228
|
+
- Developed on macOS; Linux should work, Windows is untested. Node's built-in SQLite is still marked experimental by Node; `atlas` hides its startup warning.
|
|
229
|
+
|
|
230
|
+
## Paid plans (planned)
|
|
231
|
+
|
|
232
|
+
Everything that runs on your machine is free and stays free: indexing, every query, diagrams, the MCP server. Paid plans for features that need a server (hosted indexing of private repositories, a graph shared by a team, CI integration) are in planning. Nothing is for sale yet, and prices and details are not decided.
|
|
233
|
+
|
|
234
|
+
## Agent harness
|
|
235
|
+
|
|
236
|
+
This repository is developed with AI coding agents, and its rules are enforced by tools rather than by a long instruction file:
|
|
237
|
+
|
|
238
|
+
- **`CLAUDE.md` is short.** It holds only what the code cannot tell an agent.
|
|
239
|
+
- **Lint rules carry the architecture** (`eslint.config.js`): which layer may import which, and that only one layer may touch SQLite, tree-sitter, the argument parser or the MCP SDK. Each message says what to do instead.
|
|
240
|
+
- **Hooks** (`.claude/settings.json`, scripts and tests in `.claude/hooks/`):
|
|
241
|
+
- `PreToolUse` blocks hard-to-reverse actions: broad recursive deletes, force pushes, `reset --hard`, staging secrets or index files, destructive SQL, `curl | sh`, `npm publish`, writing key-shaped strings into files.
|
|
242
|
+
- `PostToolUse` lints the file that was just edited and returns violations to the agent (exit code 2).
|
|
243
|
+
- `Stop` runs typecheck and tests when code changed, and will not let a turn end on a failure.
|
|
244
|
+
- **Deny rules** keep real env files unreadable and publishing in human hands.
|
|
245
|
+
- **Skills** (`.claude/skills/`) hold procedures that are only needed sometimes: adding a language, and proving a change with real CLI output.
|
|
246
|
+
- **A fresh-eyes reviewer** (`.claude/agents/fresh-reviewer.md`) reviews a change without having seen how it was written.
|
|
247
|
+
|
|
248
|
+
The hooks are a safety net, not a complete defense: they match command text, so a wrapped or obfuscated command can slip through, and an innocent command that merely contains a dangerous-looking string can be blocked.
|
|
249
|
+
|
|
250
|
+
## Data and privacy
|
|
251
|
+
|
|
252
|
+
- The index (`.atlas/`) stays on your machine. The folder contains its own `.gitignore`, so it is never committed by accident.
|
|
253
|
+
- The index holds file paths, symbol names, table names and env key **names**. It does not hold file contents or env values.
|
|
254
|
+
- Real env files (`.env`, `.env.local`, …) are never opened; only templates such as `.env.example` are read.
|
|
255
|
+
- No telemetry, no network requests, no API keys.
|
|
256
|
+
|
|
257
|
+
## Project layout
|
|
258
|
+
|
|
259
|
+
```
|
|
260
|
+
repo-atlas/
|
|
261
|
+
├── src/
|
|
262
|
+
│ ├── graph/ # node and edge types, in-memory graph
|
|
263
|
+
│ ├── extract/ # one file -> facts (tree-sitter, SQL, env, Markdown)
|
|
264
|
+
│ ├── indexer/ # file listing, import aliases, linking facts into a graph, incremental index
|
|
265
|
+
│ ├── store/ # SQLite (the only module that knows SQL)
|
|
266
|
+
│ ├── query/ # search, context, impact, path, mermaid, stats (pure, over the in-memory graph)
|
|
267
|
+
│ ├── app/ # Atlas: what the CLI and the MCP server both call
|
|
268
|
+
│ ├── mcp/ # MCP server
|
|
269
|
+
│ └── cli/ # the `atlas` command
|
|
270
|
+
├── test/ # extractor, linker (property-based), CLI and MCP tests
|
|
271
|
+
├── fixtures/shop/ # sample repository indexed by the tests
|
|
272
|
+
├── assets/ # README screenshots and the social preview image
|
|
273
|
+
├── scripts/ # regenerate the images in assets/ (`pnpm screenshots`)
|
|
274
|
+
├── .claude/
|
|
275
|
+
│ ├── settings.json
|
|
276
|
+
│ ├── hooks/ # dev-time hooks and their tests
|
|
277
|
+
│ ├── skills/ # add-language, verify-change
|
|
278
|
+
│ └── agents/ # fresh-reviewer
|
|
279
|
+
├── CLAUDE.md # short guidance for AI agents working in this repo
|
|
280
|
+
└── eslint.config.js # layer boundaries
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### Tech stack
|
|
284
|
+
|
|
285
|
+
TypeScript (ESM) on Node.js 22+ · [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) with prebuilt WASM grammars (no native build) · built-in `node:sqlite` · [commander](https://github.com/tj/commander.js) · [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) · Vitest and [fast-check](https://github.com/dubzzz/fast-check) · ESLint · pnpm
|
|
286
|
+
|
|
287
|
+
## Roadmap
|
|
288
|
+
|
|
289
|
+
- [x] **Phase 0**: harness: short `CLAUDE.md`, hooks, lint-enforced layers, sample repository
|
|
290
|
+
- [x] **Phase 1**: extraction: TypeScript / JavaScript / Python, SQL, env keys, Markdown
|
|
291
|
+
- [x] **Phase 2**: graph: linking, SQLite store, incremental indexing
|
|
292
|
+
- [x] **Phase 3**: queries and CLI: `search`, `context`, `impact`, `path`, `mermaid`, `stats`, `export`
|
|
293
|
+
- [x] **Phase 4**: agents: MCP server, `atlas init`
|
|
294
|
+
- [ ] **Phase 5**: release: npm package (done: `repo-atlas-cli`), more languages, IDE integration
|
|
295
|
+
- [ ] **Phase 6**: paid plans: hosted private-repository indexing, shared team graph, CI integration (planned)
|
|
296
|
+
|
|
297
|
+
## Contributing
|
|
298
|
+
|
|
299
|
+
The project is at an early stage. Please open an issue to discuss a change before sending a pull request. All files in this repository are written in English; `README.ko.md` is a Korean translation, and this file is the source of truth.
|
|
300
|
+
|
|
301
|
+
## License
|
|
302
|
+
|
|
303
|
+
[MIT](LICENSE).
|