# 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 가 부르는 주소.
- 모든 목록은 정렬 고정 — 다시 돌려도 같은 결과.

## 사이트 (478-2)

- 처음 한 번 = `./venv/Scripts/python.exe -m pip install -r docs/tools/requirements.txt` (mkdocs · Material · mkdocstrings).
- 원고 = `./venv/Scripts/python.exe docs/tools/build.py` → `docs/_build/src` · `--site` = `mkdocs build --strict` 까지 · `--stamp` = 손글 지문을 지금 함수 목록으로.
- 띄우기 = `cd docs && ../venv/Scripts/python.exe -m mkdocs serve -a 127.0.0.1:8090`
- 묶음 규칙 = `groups.yml`(계산 등록부 id · 파일 이름 무늬) · 손글 = `docs/guide/<페이지>/page.md` · `groups/<묶음>.md` · 손글 안 `[[함수]]` · `[[파일#함수]]` = 함수 칸 링크.
- 함수 화면 = TS `TypeDoc`(HTML) · 파이썬 `mkdocstrings`(griffe) — build 는 페이지 · 묶음 화면과 링크만.