Xylem은(는) 무엇을 하나요?
저장소를 소스 기반 맵으로 변환합니다. 정적 두 파일 사이트(index.html 및 deep-view.json)로 구성된 4가지 뷰를 제공합니다:
| 뷰 | 표시 내용 |
|---|---|
| 탐색(Explore) | 시스템의 구성 요소(파트)와 구성 요소 간 연결을 계층별로 그룹화하여 표시 |
| 고객 여정(Customer journeys) | 사용자가 수행할 수 있는 각 여정을 아키텍처 위에 애니메이션으로 표시: 요청, 응답 및 레이블이 지정된 핸드오프 |
| 상태 맵(State map) | 매핑된 범위 내에서 선언된 모든 상태 차원, 해당 상태, 여정이 실제로 거치는 전이를 표시 |
| 코드(Code) | 매핑된 모든 함수를 해당 영역의 타일로 표시하며, 결정 사항, 호출 및 호출자, 함수 수준에서 추적된 여정 경로를 포함 |
방법이 페이지보다 중요합니다. 모든 주장은 file:line에 연결됩니다. 모든 연결은 실제입니다. 코드가 어떤 것을 확정할 수 없는 경우, 맵은 추측하는 대신 그렇게 명시합니다.
기본 규칙 (모든 단계에 적용)
- 증거 또는 없음. 모든 구성 요소, 유닛, 결정, 엣지, 상태 및 액션은
file:line을 인용해야 합니다. 인용할 수 없으면UNVERIFIED로 표시하거나 생략합니다. 이는 작성자/검토자의 의무 사항입니다: 자동화된 게이트는 아키텍처 증거와 심층 소스 위치를 강제하지만, 모든 상태/액션 인용이나 설명의 의미를 강제하지는 않습니다. - ID 할당, 엔터티나 연결을 절대 발명하지 않음. 스캐폴드의 파일-위치 ID를 사용합니다. 수동으로 작성된 ID도 고유하고 안정적이어야 합니다. 지역 간 엣지는 선언된 아키텍처 연결을 이용해야 합니다. 연결이 없으면
diagram_gap을 기록하고 코드에서 확인한 후 증거와 함께 추가합니다. - 정직한 갭이 불가능한 경로보다 낫습니다. 여정 결과를 소스에서 별도로 추적할 수 없으면
{"unavailable": "<구체적인 이유>"}를 작성합니다. 성공 경로를 실패 결과에 절대 복사하지 마십시오. 둘 다 참일 수 없는 분기를 절대 연결하지 마십시오. - 있는 그대로 말합니다. 추적은 정적 소스 경로이며, 실제 실행 기록이 아닙니다. 페이지에서 그렇게 레이블을 지정합니다.
- 읽기 전용. 대상 저장소를 절대 편집하지 마십시오. 모든 것을
.xylem/(또는 사용자가 이름을 지정한 폴더)에 기록합니다. - 프라이버시. 사용자가 요청하지 않는 한 저장소 콘텐츠를 외부 서비스로 보내지 마십시오. 사이트는 데이터와 선택적 비디오에 대해 동일 출처 요청만 수행합니다. 외부 요청을 하지 않으므로 오프라인 사용을 위해 루프백에서 제공하십시오.
출력 레이아웃
.xylem/
census.json # 코드에서 발견된 모든 정의 (scripts/census.py)
architecture.json # 1단계
journeys.json # 2단계
deep.json # 3단계 (함수 수준 맵)
validation.json # scripts/validate.py 출력
reviews/ # 교차 검토 보고서 (6단계)
site/ # index.html + deep-view.json (+ videos/) (scripts/build_site.py)
모든 파일의 형식은 references/schemas.md에 있습니다. JSON을 작성하기 전에 먼저 읽으십시오.
단계 및 게이트
단계를 순서대로 수행하십시오. 각 단계는 게이트로 끝납니다. 게이트가 통과되거나 사용자가 문서화된 갭을 수락할 때까지 계속하지 마십시오. 명시적으로 승인된 평가판에서는 실패한 아티팩트와 로그를 변경하지 않고 보관하고 해당 평가판 범위 내에서만 계속 진행하십시오. 이후의 출력물은 잠정적이라고 표시하십시오. 구조적 통과가 완전한 의미론적 적용 범위를 설정하지는 않습니다.
0단계: 인구 조사 (결정론적)
python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]
이것은 Python AST, 표준 라이브러리 JS/TS 토큰 워커, 기타 지원 언어에 대한 근사 정규식을 사용하여 명명된 정의를 목록화합니다. scannedFiles에는 정의가 없는 소스 파일도 포함됩니다. JS/TS는 일반 화살표 함수, 구체적인 여러 줄/계산된 메서드, 오버로드 시그니처, 어휘적 함수/클래스 소유자, 정규식 리터럴 및 템플릿 보간법을 다룹니다. 익명 콜백은 인구 조사 단위가 아닙니다. 이는 측정된 인벤토리이지 모든 언어 구문의 증명이 아닙니다. 완전성을 주장하기 전에 독립적인 파서 또는 소스 샘플로 검증하십시오. 이후의 백분율은 이 인벤토리만 설명합니다.
게이트: 인구 조사 수치가 저장소 크기에 비해 그럴듯해야 합니다. 제외된 경로(예: 생성된 코드 또는 node_modules)는 정당화되어야 합니다.
1단계: 아키텍처
진입점, 빌드 파일, 주요 모듈 및 프로세스 경계를 읽습니다. 그런 다음 architecture.json을 작성합니다:
- layers: 예: shell, UI, server, domain, storage, workers, external;
- components: 각각
id,layer,files[], 간결한 책임,processType; - connections: 각각
{from, to, label, kind},kind는 spawn, ipc, http, file, data 또는 uses 중 하나; - flows: 주요 종단 간 흐름을 정렬된 구성 요소 단계로 나타냅니다.
게이트: python scripts/validate.py .xylem --only architecture가 통과되어야 합니다. 모든 scannedFiles 항목은 구성 요소에 속하거나, 이유가 명시된 architecture.meta.fileExclusions 항목이 있어야 합니다. 증거 경로와 라인은 증거 루트 아래에 존재해야 합니다.
2단계: 여정 및 상태
journeys.json을 작성합니다. UI, 라우트, CLI 명령, 작업 및 오류 경로에서 이를 파악합니다:
- stateDimensions: 모든 독립적인 상태 머신;
- screens: 모든 화면;
- actions: 각 사용자 액션 및 시스템 전이, 그 결과, 사용자가 보는 정확한 텍스트, 실행 취소;
- journeys: 시작 상태와 단계.
모든 액션은 정렬된 아키텍처 추적(구성 요소와 연결을 번갈아 가며)을 전달합니다. 반환 구간은 {"connection": [a, b], "direction": "reply"}를 사용합니다. 다음 단계가 마지막 단계가 끝난 곳에서 시작하지 않으면, 단계는 유형과 레이블(user, timer, queue, continuation, lifecycle 또는 download)이 있는 transition.handoff를 전달합니다. 행복, 불행, 복구 및 엣지 여정을 다루십시오.
게이트: validate.py --only journeys가 통과:
- 모든 여정이 유효한 결과를 통해 재생됨;
- 무음 점프 제로 (각 조명은 유선, 응답 또는 레이블이 지정된 핸드오프를 통해 도달됨);
- 고아 상태 없음.
3단계: 함수 수준 맵 (최종 해상도)
- 인구 조사에서 초안 맵을 생성합니다:
python scripts/scaffold_deep.py .xylem
deep.json을 작성합니다. 초안에는 할당된 인구 조사 단위, AST의 Python 결정, 휴리스틱 JS/TS if, while, for, switch 및 괄호로 묶인 catch 지점이 포함됩니다. JS/TS는 삼항 연산자, 계산 또는 단락 결정의 완전한 인벤토리를 주장하지 않습니다. 주석, 리터럴 내용 및 자식 선언은 각 본문에서 제외됩니다. 제네릭 호출은 별도의 호출 위치를 유지합니다. 호출 엣지는 source: heuristic 및 confidence: name-resolved를 사용합니다. 해결되지 않은 이름은 발명된 링크가 아닙니다. 소스에 대해 정제하십시오. 이름 해결은 타입 해결이 아닙니다.
2. 코드를 읽어 초안을 정제합니다:
- 유닛당 비즈니스 판독 가능
summary, 이름이 아닌 본문에서 작성; - 모든 결정에 대해,
plain질문("이 파일이 16MiB보다 큽니까?")과 정확한 코드test,kind(branch, calculation, loop 또는 unconditional) 및 올바른 후속 작업.return또는raise는 경로를 종료합니다. try 블록의 정상 및 오류 연속은 별개이며, 보류 중인 예외는finally를 실행한 다음 전파됩니다. 확실하지 않은 경우 후속 작업을unresolved로 표시하고, 절대verified로 표시하지 마십시오; risk태그는 알려진 결함을 직접 구현하는 결정에만 적용합니다.
actionTraces작성: 각 여정 액션 및 결과에 대해, 정렬된 실행 이벤트{component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}.event는 call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally 또는 resume 중 하나입니다. 활성화 프레임, 터미널 이벤트 및 지원되는 재생 제한에 대한 스키마를 참조하십시오.- 실제 개시자(예: UI 핸들러, 라우트 또는 작업)에서 시작합니다.
- 호출, 반환 및 프로세스 경계를 따릅니다. 거부는 실제 오류 경로를 따라 사용자에게 돌아가야 합니다. "저장됨" 또는 "성공"으로 계속되어서는 안 됩니다.
- 경로를 알 수 없는 경우
{"event": "unknown", "note": "..."}를 내보내거나 전체 결과를 사용 불가능으로 표시합니다.
대규모 저장소: 여러 에이전트가 코드 영역별로 3단계를 분할하고, 각각 동일한 형식으로 deep-<part>.json을 작성한 다음 scripts/merge_deep.py로 병합합니다. 이름 유사성이 아닌 파일 및 정의 라인으로 ID를 조정합니다.
게이트: validate.py가 전체 세트를 통과:
- 모든 인구 조사 정의가 내보내지거나 이유와 함께 명시적으로 제외됨; 내보낸 적용 범위와 제외 회계는 별도의 카운터입니다;
- 모든 엣지 엔드포인트가 해결됨;
- 모든 지역 간 엣지가 연결을 이용함;
- 결정 후속 작업이 해결됨;
- 추적 참조가 유효함;
- 선택기 일관성: 변경되지 않은 값에 대해 상호 배타적인 선택을 하는 활성화가 없음. 소스 쓰기는 값을 변경할 수 있습니다. 반복 레이블만으로는 제약 조건을 재설정할 수 없습니다. 지원되는 문법 및 제한은 스키마에 있습니다. 예를 들어,
x==='a'예 그리고x==='b'예, 또는 값이 제외된 다음includes()에 의해 요구됨. 추적을 수정하거나, 갈등을 명명하여unavailable로 철회하십시오.
4단계: 페이지 구축
python scripts/build_site.py .xylem
이것은 site/index.html 및 site/deep-view.json을 작성합니다. 비디오는 선택 사항입니다: 먼저 videos/<journeyId>.mp4 및 videos/manifest.json을 .xylem/에 넣으십시오(스키마 참조). 보려면 site/를 HTTP로 제공하십시오(예: python -m http.server -d .xylem/site). file:// 페이지는 코드 뷰의 데이터를 로드할 수 없습니다.
게이트: 페이지를 열고 각 모드를 한 번씩 확인:
- 콘솔 오류 없음;
- 전화 너비(420px)에서 가로 스크롤 없음;
- 키보드 및 다크 모드가 작동합니다.
5단계: 선택적 실제 화면 녹화
로컬에서 실행할 수 있는 UI가 있는 앱의 경우 Playwright로 여정을 녹화하십시오. 시작점은 scripts/record_journey.example.mjs입니다. 녹화 규칙:
- 모의 응답 없이 실제 UI를 구동합니다;
- 단계당 캡션을 추가합니다;
- 유휴 대기를 가속화하고 가속화를 캡션에 표시합니다;
manifest.json에 단계별atSec을 기록합니다;- 부분 녹화는 부분적이라고 표시합니다.
뷰어는 비디오를 맵에 동기화하므로 비디오가 클록이 됩니다.
6단계: 교차 검토 위원회
가능하면 두 명의 독립적인 검토자를 사용하십시오: 두 개의 다른 모델 또는 에이전트, 또는 최소한 작성자의 추론에 접근할 수 없는 새로운 컨텍스트를 사용하십시오. references/protocol.md를 따르십시오:
- 작성자는 자신의 작업을 평가하지 않습니다;
- 검토자는 파일과 코드를 받고 작성자의 결론은 받지 않습니다;
- 검토자는 독립적인 검사기를 실행하고 소스에 대한 주장을 샘플링합니다: protocol.md의 단일 샘플링 규칙(최소값 미만의 모든 사용 가능한 항목);
- 결과는 심각도, 증거 및 구체적인 수정 사항과 함께
reviews/<reviewer>-<round>.md로 이동합니다; - 수락 게이트: 아키텍처, 여정, 심층, 페이지/데이터 및 동결 번들에 대한 명시적 ACCEPT, REJECT 또는 BLOCKED. 중대한 결함만이 REJECT를 정당화합니다: 잘못된 결론, 불가능한 경로 또는 차단된 핵심 작업. 선언된 제한, 정직한
unavailable마커 및 추적의 정적 특성은 거부 사유가 아닙니다; - 제한된 검토 예산을 사용하고, 해결되지 않은 경우 REJECT/BLOCKED 및 보존된 증거와 함께 중단합니다. 설명이 아닌 정확히 구축된 아티팩트를 재검토합니다.
게이트: 모든 동결 번들 아티팩트가 독립적인 검토에 의해 수락됩니다. 샘플링 할당량을 충족하기 위해 경로를 절대 조작하지 마십시오.
7단계: 게시 및 보고
페이지에 무엇이 있는지 실제 수치와 함께 사용자에게 알립니다:
- 함수, 결정, 여정 및 추적된 결과 수;
- 사용 불가능한 결과 수와 그 이유;
- 교차 검토된 내용.
한계를 명확하게 보고합니다.
스크립트
| 스크립트 | 목적 |
|---|---|
census.py | 다중 언어 정의 인구 조사 (커버리지 분모) |
scaffold_deep.py | 인구 조사 및 아키텍처에서 함수 수준 맵 초안 작성 |
merge_deep.py | 부분 맵 병합; 파일 및 라인으로 ID 조정 |
validate.py | 모든 게이트: 스키마, 참조, 커버리지, 무음 점프, 후속 작업, 선택기 일관성 |
build_site.py | 컴팩트 코드 뷰 데이터 내보내기 및 단일 페이지 사이트 구축 |
record_journey.example.mjs | 실제 화면 여정 비디오를 위한 Playwright 시작점 |
Python 스크립트는 Python 3.9+ 및 표준 라이브러리만 필요로 합니다. 선택적 .mjs 브라우저/녹화 도우미는 별도로 사용 가능한 Playwright가 필요합니다. 페이지는 프레임워크나 외부 요청을 사용하지 않습니다.