eomsangdonandClaude Opus 5.5
9e315a8abb
- extract_ts.mjs — 함수(kind · exported · doc · params · returns · calls · called_by · 다시 내보내기) · 세션 칸 · 서버 주소 글자 · 계산 등록부 그대로 - extract_py.py — def 전부 · docstring 첫 줄 · 부르는 함수 · FastAPI 라우트 데코레이터 - extract_api.py — 서버 안 켜고 openapi 주소 → handler · TS 부르는 곳 짝 · 짝 없는 것 따로 - 범위 = scope.json 한 곳 · 세는 규칙 = README · 시험 test_478_extract(6) - 수치 = 함수 5746 · 세션 칸 45 · 서버 주소 41 · 등록부 45 · 14.3 s Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
33 lines
4.0 KiB
Markdown
33 lines
4.0 KiB
Markdown
# docs/tools — 프로그램 문서 추출 (PLAN 478)
|
|
|
|
- 한 명령 = `./venv/Scripts/python.exe docs/tools/extract_all.py` → `docs/_data/` (git 밖).
|
|
- 처음 한 번 = `npm --prefix docs/tools install` (ts-morph · 루트 npm install 금지).
|
|
- 범위 = `scope.json` 한 곳 — `roots` 폴더 전부 + 거기서 import 로 닿는 `follow` 폴더 파일(파이썬은 계산 등록부가 짚는 `follow` 파일도).
|
|
|
|
## 만드는 것
|
|
|
|
| 파일 | 내용 |
|
|
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `functions.json` | 함수 [{id, lang, file, line, name, kind, exported, doc, params, returns, calls, called_by}] · 파이썬 라우트 함수 = `routes` · 다시 내보내기 = `target` |
|
|
| `session_keys.json` | 세션 칸 [{key, reads, writes}] |
|
|
| `api.json` | 서버 주소 [{method, path, handler, callers}] |
|
|
| `api_unmatched.json` | 짝 없는 TS 주소 글자 · 부르는 TS 없는 범위 주소 |
|
|
| `registry.json` | 계산 등록부(`design_calc_registry*.ts`) 항목 그대로 |
|
|
| `raw/` | 중간 결과(TS 함수 · 파이썬 함수 · TS 주소 글자) |
|
|
|
|
## 세는 규칙
|
|
|
|
- id = `ts:<파일>#<이름>` · `py:<파일>#<이름>` · 이름 = 감싼 클래스 · 함수 · 변수 이름을 점으로 이음(`Class.method` · `outer.inner` · `obj.prop`) · 같은 id 가 또 나오면 소스 차례대로 `~2` · `~3`.
|
|
- TS 에서 세는 것: 몸통 있는 `function`(이름 없는 기본 export = `default`) · 변수 · 속성 · 클래스 칸에 담긴 화살표 · 함수 식 · 클래스 메서드 · 접근자 · 생성자(`constructor`) · 함수를 가리키는 다시 내보내기(`export { a as b } from` · `export default foo` → kind `reexport`).
|
|
- TS 에서 안 세는 것: 이름 없는 콜백(그 안의 부름은 감싼 함수 몫) · 오버로드 선언 · 타입 · `export * from`.
|
|
- 파이썬에서 세는 것: `def` · `async def` 전부(메서드 · 안쪽 함수 포함). 안 세는 것: `lambda`(그 안의 부름은 감싼 함수 몫).
|
|
- kind = `function` · `arrow` · `method` · `reexport`.
|
|
- exported = TS 맨 위 `export` · 내보낸 클래스의 private 아닌 메서드 · 파이썬 맨 위(또는 맨 위 클래스) 의 `_` 로 시작하지 않는 이름.
|
|
- 기성 도구(TypeDoc · griffe)와 맞댈 때 = `exported` 가 참인 것만 · 파일 · 이름 · 줄 · kind 로.
|
|
- calls = 범위 안 함수만(범위 밖 · 이름 못 푸는 부름은 뺌).
|
|
- doc = JSDoc · docstring 의 첫 줄(`@` 태그 줄 뺌) · 없으면 null.
|
|
- 세션 칸 = `b_page_state` 의 `readState` · `readStateRaw` · `readByKey`(읽기) · `writeState` · `writeStateRaw` · `writeByKey` · `clearState`(쓰기) · `sessionStorage.getItem`(읽기) · `setItem` · `removeItem`(쓰기) · 열쇠를 글자로 못 풀면 `{식}`.
|
|
- 서버 주소 = 함수 안 `/` 로 시작하는 글자 · 템플릿(`${…}` = `{}` · 앞 `/api` 뗌 · `?` 뒤 뗌) → 경로 칸끼리 짝(서버 `{x}` · TS `{}` = 아무 칸 · 어긋남 적은 것) · 메서드 = 옆 옵션의 `method`(변수 · 펼침 = 아무 메서드 · 옵션에 없으면 GET).
|
|
- api.json 범위 = 범위 파이썬이 받거나 범위 TS 가 부르는 주소.
|
|
- 모든 목록은 정렬 고정 — 다시 돌려도 같은 결과.
|