P31 폴더 파일 목록을 깊이별로 기록하고 못 본 범위 구분하기
버전 1.0.0 / Python 3.12 표준 라이브러리 / 2026-10-05

목표
파일 내용을 열거나 해시하지 않고 상대 경로, 종류, 일반 파일 크기와 조회 범위를 기록합니다.
기준 root 밖의 새 JSON 한 개를 저장합니다. 목록 코드에는 원본 이동, 삭제, 쓰기 기능이 없습니다.
setup_fixture.py는 새 가상 입력을 만드는 준비 도구입니다.

실행 위치
이 ZIP을 새 빈 폴더에 풀고 이 README.txt가 있는 최상위 위치에서 터미널을 엽니다.
회사 원본 대신 fixtures/root를 먼저 사용합니다. 별도 패키지는 설치하지 않습니다.
Python 3.12를 사용하세요. python3만 있다면 아래 python 실행 이름을 모두 python3으로 바꿉니다.

독자 명령
python --version
python code/inventory.py fixtures/root --depth 0 --output inventory-depth0.json
python code/inventory.py fixtures/root --depth 1 --output inventory-depth1.json
python code/inventory.py fixtures/root --depth 2 --output inventory-depth2.json
python -m unittest discover -s tests -v

깊이 계약과 검산
깊이 0 = root 바로 아래 항목: 일반 파일 2개, 12바이트, sub 내부 미검사
깊이 1 = 하위 1단계 항목까지: 일반 파일 3개, 16바이트, sub/deep 내부 미검사
깊이 2 = 하위 2단계 항목까지: 일반 파일 4개, 20바이트, 기본 가상 트리의 하위 열거 완료
root의 .keep(5바이트), report.txt(7바이트), sub/one.txt(4바이트), sub/deep/two.txt(4바이트)
일반 파일만 크기를 숫자로 표시하며 폴더, 링크, 특수 파일, 종류 미확인은 null입니다.
숨김 항목을 포함하고 상대 경로는 /로 구분합니다. 정렬은 Unicode 코드포인트 순서입니다.
크기 합은 논리적 파일 크기 합이며 실제 디스크 사용량이 아닙니다.

출력과 상태
화면 JSON과 저장 JSON은 같습니다. root의 .은 명령에 지정한 검사 root입니다.
expected/depth0.json, depth1.json, depth2.json이 기본 전체 기대값입니다.
scope_complete=true는 지정 깊이와 링크 미추적 정책 안의 조회 오류가 없다는 뜻입니다.
depth_limit 보류가 있으면 scope_complete=true여도 whole_tree_enumerated=false입니다.
whole_tree_enumerated=true도 파일 내용을 확인했다는 뜻은 아닙니다. content_read는 false입니다.
오류가 있으면 summary는 부분 관찰값이며 최종 목록으로 채택하지 않습니다.
종료 코드: 0=지정 범위 조회 오류 없음, 1=부분 조회 오류, 2=인수/경로/저장 오류
기존 보고서를 덮어쓰지 않습니다. 같은 출력 이름은 종료 코드 2입니다.
다시 검사할 때는 다음처럼 새 이름을 씁니다.
python code/inventory.py fixtures/root --depth 1 --output inventory-depth1-02.json
저장 중 디스크 오류로 불완전한 새 JSON이 남을 수 있습니다. 코드 2 출력을 정상 결과로 쓰지 않습니다.

종류와 범위
file, directory, symlink, junction, reparse_point, special, unknown을 구분합니다.
심볼릭 링크는 따라가지 않고 Windows에서 관찰한 junction/reparse_point 메타데이터는 내부 순회를 보류합니다.
junction은 MOUNT_POINT 태그를 사용한 보수적 표시이며 세부 형식 인증이 아닙니다.
root 자체와 root/출력 경로의 부모 구성요소에서 링크 또는 재분석 지점이 확인되면 거부합니다.
Windows lstat의 일부 다른 재분석 지점은 OS가 해석할 수 있어 모든 재분석 기능의 사전 차단을 보장하지 않습니다.
.. 경로는 거부하며 출력은 root 밖의 새 .json이어야 합니다. 부모 폴더는 이미 있어야 합니다.
empty=정상적으로 열거한 빈 폴더, read_failed=조회 실패입니다. 두 상태를 합치지 않습니다.
permission_denied와 다른 io_error는 errors에서 따로 확인합니다.
깊이는 0~20, 기본 1입니다. 전체 열거 항목 한도는 2,000개입니다.
한도 초과 확인용 이름 하나를 포함해 최대 2,001개를 조회하고 추가 이름은 결과에 넣지 않습니다.
실패/한도 초과 디렉터리의 먼저 나온 일부 이름을 정상 결과로 채택하지 않습니다.

선택 링크 실습
기본 ZIP에는 링크를 넣지 않았습니다. 새 단일 폴더 이름만 setup에 지정할 수 있습니다.
python setup_fixture.py --root practice_link --with-link
python code/inventory.py practice_link --depth 1 --output inventory-link-depth1.json
첫 setup 명령이 성공했을 때만 목록 명령을 실행합니다.
shortcut은 sub를 가리키며 따라가지 않습니다. 깊이 0/1/2의 파일 수는 2/3/4 그대로, links는 각각 1입니다.
expected/with_link_depth0_linux.json, with_link_depth1_linux.json, with_link_depth2_linux.json 참고
setup이 링크 생성에 실패하면 일반 파일 4개는 남을 수 있고 종료 코드 1을 반환합니다.
Windows에서는 링크 생성 권한이 제한될 수 있습니다. 권한/보안 설정을 바꾸지 말고 기본 fixture로 실습하세요.
기존 practice_link가 있으면 setup은 덮어쓰지 않고 종료 코드 2입니다. 다른 새 이름을 지정합니다.

시험 범위
실행 환경: CPython 3.12.14 / Linux 6.18.44 / x86_64 / effective UID 1000
python -m unittest discover -s tests -v : 40개 통과, 0개 건너뜀
격리한 가상 폴더에서 깊이 2/3/4개, 숨김 포함, empty, 기존 출력, 재실행, 누락/파일 root,
음수/상한 깊이, 전체 항목 한도, symlink, POSIX FIFO, 내용 미개방, 원본 경로/바이트/mtime 보존,
실제 POSIX 권한거부, 권한거부 모의시험, 조회 중 파일/폴더 변경을 확인했습니다.
Windows junction/기타 reparse 분류와 부모 경로 거부는 메타데이터 모의시험입니다.
Windows와 macOS 실제 실행은 하지 않았습니다. Windows 링크 권한 제약도 실제 시험하지 않았습니다.
test_results/environment.json, unittest_linux.txt, cli_checks.json, actual_permission_linux.json 참고
메타데이터 재조회는 일부 변경만 발견하며 원자적 스냅샷이나 악의적 경로 교체 방어를 보장하지 않습니다.
읽기 전용은 원본 내용/경로를 쓰거나 바꾸지 않는다는 뜻이고 OS 접근시각 고정은 아닙니다.

파일 확인
SHA256SUMS.txt는 패키지 파일 확인용입니다. inventory.py는 root 파일 내용을 해시하지 않습니다.
