pythograph 0.2.0__tar.gz → 0.2.2__tar.gz

{pythograph-0.2.0 → pythograph-0.2.2}/CHANGELOG.md

@@ -4,6 +4,31 @@
 
 ## [Unreleased]
 
+## [0.2.2] - Unreleased
+
+릴리스 준비 중이며 아직 PyPI에 발행하지 않았다. 게시 후 실제 공개 날짜를 기록한다.
+
+### Fixed
+
+- 같은 검색 루트의 `name.py`와 `name/__init__.py`가 공존하면 Python import와 같이 일반 패키지를 먼저
+  선택한다. 가려진 모듈로 향하던 거짓 직접 호출 간선과 실제 패키지 대상의 누락을 바로잡는다.
+
+- 모듈·패키지 이름 해석과 소스·의존성 선언 읽기에서 마지막 파일뿐 아니라 모든 프로젝트 상대 경로 성분의 링크를
+  거부한다. Django settings·URLconf 문자열이 링크 부모를 통해 프로젝트 밖 파일의 사실을 가져오던 경계를 바로잡는다.
+- 내부를 가리키는 링크와 Windows 디렉터리 junction도 제외하며, 같은 링크는 중복 없이 한계에 센다.
+- 지원하는 운영체제에서는 디렉터리 핸들 상대 `O_NOFOLLOW`로 순회·읽기를 고정하고, 읽기 전에 파일 신원을 확인한다.
+  링크 교체 경쟁 회귀 테스트와 대체 경로의 원자성 한계를 문서화한다. 분석 대상 코드는 여전히 import·실행하지 않는다.
+
+- 파일 전체를 읽은 뒤 자르던 경로를 제한된 스트림 읽기로 바꿔 4 MiB 상한을 실제 메모리 사용에 적용한다.
+- 디렉터리 전체를 정렬하기 전에 순회 항목 상한을 적용한다. 초과 디렉터리는 임의 부분 수확 대신 통째로 제외하고 한계를 남긴다.
+- 디렉터리·항목 읽기 실패를 모든 생산자의 한계에 세고, 누락 모듈이 있는데도 `bound` 근거를 확정하던 경로를 막는다.
+
+## [0.2.1] - 2026-10-01
+
+### Fixed
+
+- SQL FROM/JOIN의 테이블 값 함수를 관계로 추측하지 않고 미해석 피연산자로 센다.
+
 ## [0.2.0] - 2026-10-01
 
 0.1.0 이후 #7–#12를 담는다. 클라이언트 route-call(`routes --role client`, #10)로 파이썬 호출부를 서버 route에 잇고, `bound` 근거

{pythograph-0.2.0 → pythograph-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pythograph
-Version: 0.2.0
+Version: 0.2.2
 Summary: Static facts for Python (Django, Django REST framework, Flask, SQLAlchemy) services for the isthmus bridge-facts exchange: HTTP route declarations and persistence relation uses from the standard-library ast, without importing the analyzed project.
 Project-URL: Homepage, https://github.com/ictechgy/pythograph
 Project-URL: Repository, https://github.com/ictechgy/pythograph
@@ -29,6 +29,8 @@ Description-Content-Type: text/markdown
 
 # pythograph
 
+<img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph's blue tit mascot" width="112" height="112" align="right">
+
 [한국어](https://github.com/ictechgy/pythograph/blob/main/README.ko.md)
 
 Static facts for Python services (Django, Django REST framework, Flask, SQLAlchemy), emitted in the
@@ -378,6 +380,21 @@ client `route-call` facts (`routes --role client`), persistence `relation-use` f
 analyses (`language-traversal` v1) in `trace`. Earlier isthmus releases reject python route-decl and route-call
 documents as input errors. `--dispatch specificity` remains for those older releases.
 
+## Bounded source scanning
+
+Source reads request at most 4 MiB plus one overflow byte. Directory enumeration consumes at most 200,000 entries
+plus one overflow entry, with a maximum depth of 64. An oversized directory is omitted as a whole rather than selecting
+an arbitrary filesystem-order subset; files from previously completed directories remain available. Unreadable directory
+entries are counted in limitations for routes, schema, and graph output, and prevent closed-world `bound` proofs that
+would otherwise rely on missing modules. A successful command with these limitations is still an incomplete analysis.
+
+Every project-relative path component is checked for symbolic links, including module/package resolution and dependency
+manifests. Links to locations inside the project are rejected too; the skipped-link count counts each encountered path
+once. On systems supporting descriptor-relative `O_NOFOLLOW`, directory scans and source reads open each component
+without following links, and verify the opened file before reading. Other systems recheck components and file identity
+before reading, but those checks are not atomic. Analyze a stable project tree; this is not a filesystem snapshot or a
+sandbox against concurrent changes to the filesystem. The analyzed Python code is never imported or executed.
+
 ## Development
 
 ```sh

{pythograph-0.2.0 → pythograph-0.2.2}/README.ko.md

@@ -1,5 +1,7 @@
 # pythograph
 
+<img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph의 푸른박새 마스코트" width="112" height="112" align="right">
+
 [English](README.md)
 
 Python 서비스(Django, Django REST framework, Flask, SQLAlchemy)의 정적 사실을
@@ -279,6 +281,19 @@ isthmus-cli 0.10.0(npm, `npm install --global isthmus-cli@0.10.0`)이 `platform:
 persistence `relation-use`, trace의 python `forward`·`reverse` 분석(`language-traversal` v1). 그 전 isthmus 릴리스는 python
 route-decl·route-call 문서를 입력 오류로 거부한다. 그런 옛 판용 `--dispatch specificity`는 그대로 남아 있다.
 
+## 소스 읽기 상한
+
+파일은 최대 4 MiB와 초과 확인용 1바이트만 읽습니다. 디렉터리 열거는 최대 200,000개와 초과 확인용 항목 하나,
+깊이는 64까지입니다. 상한을 넘는 디렉터리는 파일시스템 열거 순서에 따른 임의의 일부 대신 전체를 제외하고,
+앞서 완전히 순회한 디렉터리의 파일은 보존합니다. 읽지 못한 디렉터리 항목 수는 routes·schema·graph 한계에 남기고,
+보이지 않는 모듈에 의존하는 닫힌 세계 `bound` 증명도 막습니다. 이런 한계와 함께 성공한 명령은 여전히 불완전한 분석입니다.
+
+모듈·패키지 이름 해석과 의존성 선언 파일을 포함해 프로젝트 상대 경로의 모든 성분에서 심볼릭 링크를 검사합니다.
+프로젝트 내부를 가리키는 링크도 거부하며, 발견한 같은 링크 경로는 한 번만 셉니다. 디렉터리 핸들 상대 `O_NOFOLLOW`를
+지원하는 운영체제에서는 순회와 소스 읽기 때 각 성분을 링크를 따라가지 않고 열고, 읽기 전에 열린 파일의 신원도 확인합니다.
+다른 운영체제에서는 읽기 전에 경로 성분과 파일 신원을 재검사하지만 원자적인 검사는 아닙니다. 변경 중이 아닌 프로젝트를
+분석하세요. 파일시스템 스냅샷이나 동시 변경에 대한 샌드박스는 아닙니다. 분석 대상 Python 코드는 import·실행하지 않습니다.
+
 ## 개발
 
 ```sh

{pythograph-0.2.0 → pythograph-0.2.2}/README.md

@@ -1,5 +1,7 @@
 # pythograph
 
+<img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph's blue tit mascot" width="112" height="112" align="right">
+
 [한국어](https://github.com/ictechgy/pythograph/blob/main/README.ko.md)
 
 Static facts for Python services (Django, Django REST framework, Flask, SQLAlchemy), emitted in the
@@ -349,6 +351,21 @@ client `route-call` facts (`routes --role client`), persistence `relation-use` f
 analyses (`language-traversal` v1) in `trace`. Earlier isthmus releases reject python route-decl and route-call
 documents as input errors. `--dispatch specificity` remains for those older releases.
 
+## Bounded source scanning
+
+Source reads request at most 4 MiB plus one overflow byte. Directory enumeration consumes at most 200,000 entries
+plus one overflow entry, with a maximum depth of 64. An oversized directory is omitted as a whole rather than selecting
+an arbitrary filesystem-order subset; files from previously completed directories remain available. Unreadable directory
+entries are counted in limitations for routes, schema, and graph output, and prevent closed-world `bound` proofs that
+would otherwise rely on missing modules. A successful command with these limitations is still an incomplete analysis.
+
+Every project-relative path component is checked for symbolic links, including module/package resolution and dependency
+manifests. Links to locations inside the project are rejected too; the skipped-link count counts each encountered path
+once. On systems supporting descriptor-relative `O_NOFOLLOW`, directory scans and source reads open each component
+without following links, and verify the opened file before reading. Other systems recheck components and file identity
+before reading, but those checks are not atomic. Analyze a stable project tree; this is not a filesystem snapshot or a
+sandbox against concurrent changes to the filesystem. The analyzed Python code is never imported or executed.
+
 ## Development
 
 ```sh

{pythograph-0.2.0 → pythograph-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pythograph"
-version = "0.2.0"
+version = "0.2.2"
 description = "Static facts for Python (Django, Django REST framework, Flask, SQLAlchemy) services for the isthmus bridge-facts exchange: HTTP route declarations and persistence relation uses from the standard-library ast, without importing the analyzed project."
 readme = "README.md"
 license = "MIT"

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/__init__.py

@@ -4,4 +4,4 @@
 """
 
 #: 배포 버전. `pyproject.toml`의 `project.version`과 같아야 한다(테스트가 대조한다).
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/graph/exposure.py

@@ -338,8 +338,16 @@ def collect_program(project: Project, index: DefinitionIndex, resolver: Resolver
         모은 사실.
     """
     facts = ProgramFacts(library=detect_library(project), whole=whole)
-    if project.scan_capped or project.skipped_links or project.unencodable_names or index.unparsed:
-        facts.incomplete = "the scan is incomplete (unparsed files, skipped links, or the file limit)"
+    if (
+        project.scan_capped
+        or project.skipped_links
+        or project.unencodable_names
+        or project.scan_errors
+        or index.unparsed
+    ):
+        facts.incomplete = (
+            "the scan is incomplete (unreadable entries, unparsed files, skipped links, or the file limit)"
+        )
     names = _definition_names(index, whole)
     for definition in sorted(index.definitions.values(), key=lambda item: item.id):
         if whole or not is_test_path(definition.path):

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/graph/limitations.py

@@ -173,4 +173,9 @@ def _scan_lines(project: Project, statistics: dict[str, object]) -> list[str]:
             "scan-incomplete: the file walk stopped at a limit or skipped symbolic links or undecodable names; "
             "symbols in those files are missing"
         )
+    if project.scan_errors:
+        lines.append(
+            f"scan-incomplete: {project.scan_errors} directory entries could not be read; "
+            "symbols in those paths may be missing"
+        )
     return lines

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/persistence/command.py

@@ -277,6 +277,11 @@ def _project_gaps(project: Project, extraction: PersistenceExtraction) -> None:
     """
     if project.scan_capped:
         extraction.add_gap("scan-truncated:", "the project scan stopped at its entry or depth limit")
+    if project.scan_errors:
+        extraction.add_gap(
+            "unreadable-sources:",
+            f"{project.scan_errors} directory entries could not be read; the project scan is incomplete",
+        )
     if project.unencodable_names:
         extraction.add_gap(
             "unreadable-sources:", f"{project.unencodable_names} Python files have names that are not valid UTF-8"

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/persistence/sql.py

@@ -586,6 +586,12 @@ class _RelationScan:
                 self.unresolved += 1
             return None
         name, after_name = read
+        # FROM/JOIN의 함수는 관계 신원이 아니다. INSERT의 컬럼 목록은 그대로 읽는다.
+        if keyword.text.lower() in {"from", "join"} and self._is_symbol(after_name, "("):
+            self.unresolved += 1
+            for consumed in range(index, after_name):
+                self.consumed[consumed] = True
+            return _skip_parens(self.tokens, after_name)
         if buffer is None:
             self._emit(name, keyword)
         else:

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/routes/client/extract.py

@@ -808,6 +808,10 @@ def _project_gaps(project: Project, extraction: ClientExtraction) -> None:
     """
     if project.scan_capped:
         extraction.add_gap(COVERAGE, "the project scan stopped at its entry or depth limit")
+    if project.scan_errors:
+        extraction.add_gap(
+            COVERAGE, f"{project.scan_errors} directory entries could not be read; the project scan is incomplete"
+        )
     if project.unencodable_names:
         extraction.add_gap(
             COVERAGE,

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/routes/command.py

@@ -104,6 +104,11 @@ def _project_gaps(project: Project, extraction: Extraction) -> None:
     """
     if project.scan_capped:
         extraction.add_gap("route-coverage:", "the project scan stopped at its entry or depth limit")
+    if project.scan_errors:
+        extraction.add_gap(
+            "route-coverage:",
+            f"{project.scan_errors} directory entries could not be read; the project scan is incomplete",
+        )
     if project.unencodable_names:
         extraction.add_gap(
             "route-coverage:",

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/routes/versions.py

@@ -95,21 +95,22 @@ def _requirement_files(project: Project, root: str) -> list[str]:
     Returns:
         경로 목록.
     """
-    directory = project.root / root if root else project.root
     found: list[str] = []
     try:
-        entries = sorted(directory.iterdir())
+        with project.scan_directory(root) as iterator:
+            names = sorted(entry.name for entry in iterator)
     except OSError:
         return found
-    for entry in entries:
-        relative = PurePosixPath(root, entry.name).as_posix() if root else entry.name
-        if entry.name.startswith("requirements") and entry.name.endswith(".txt"):
+    for name in names:
+        relative = PurePosixPath(root, name).as_posix() if root else name
+        if name.startswith("requirements") and name.endswith(".txt"):
             found.append(relative)
-        elif entry.name == "requirements" and project.is_directory(relative):
+        elif name == "requirements" and project.is_directory(relative):
             try:
-                found.extend(
-                    f"{relative}/{child.name}" for child in sorted(entry.iterdir()) if child.name.endswith(".txt")
-                )
+                with project.scan_directory(relative) as iterator:
+                    found.extend(
+                        sorted(f"{relative}/{child.name}" for child in iterator if child.name.endswith(".txt"))
+                    )
             except OSError:
                 continue
     return found

{pythograph-0.2.0 → pythograph-0.2.2}/src/pythograph/source/project.py

@@ -12,8 +12,11 @@ from __future__ import annotations
 import ast
 import os
 import stat
+from collections.abc import Iterator
+from contextlib import contextmanager
 from dataclasses import dataclass, field
-from pathlib import Path, PurePosixPath
+from itertools import islice
+from pathlib import Path, PurePosixPath, PureWindowsPath
 
 #: 읽을 파이썬 파일의 최대 크기(바이트)다. 더 크면 생성물로 보고 건너뛴다.
 MAX_SOURCE_BYTES = 4 * 1024 * 1024
@@ -24,6 +27,14 @@ MAX_SCANNED_ENTRIES = 200_000
 #: 순회할 최대 디렉터리 깊이다.
 MAX_SCAN_DEPTH = 64
 
+#: 지원하는 운영체제에서는 디렉터리 핸들에 상대적으로 열어 링크 교체 경쟁을 막는다.
+_HAS_DIR_FD = (
+    os.open in os.supports_dir_fd
+    and os.scandir in os.supports_fd
+    and hasattr(os, "O_NOFOLLOW")
+    and hasattr(os, "O_DIRECTORY")
+)
+
 #: 순회에서 건너뛰는 디렉터리 이름이다(가상 환경·캐시·빌드 산출물·의존성).
 SKIPPED_DIRECTORIES = frozenset(
     {
@@ -82,6 +93,8 @@ class Project:
     skipped_links: int = 0
     scan_capped: bool = False
     unencodable_names: int = 0
+    scan_errors: int = 0
+    _skipped_link_paths: set[str] = field(default_factory=set)
 
     @classmethod
     def open(cls, root: Path) -> Project:
@@ -129,33 +142,47 @@ class Project:
             발견한 `.py` 파일의 프로젝트 상대 경로.
         """
         found: list[str] = []
-        pending: list[tuple[Path, int]] = [(self.root, 0)]
+        pending: list[tuple[str, int]] = [("", 0)]
         scanned = 0
         while pending:
             directory, depth = pending.pop()
+            remaining = MAX_SCANNED_ENTRIES - scanned
+            entries: list[os.DirEntry[str]] = []
             try:
-                entries = sorted(os.scandir(directory), key=lambda entry: entry.name)
+                with self.scan_directory(directory) as iterator:
+                    for entry in islice(iterator, remaining + 1):
+                        scanned += 1
+                        entries.append(entry)
+                    if scanned > MAX_SCANNED_ENTRIES:
+                        # 파일시스템 열거 순서는 안정적이지 않다. 상한을 넘은 디렉터리는
+                        # 임의의 접두사만 분석하지 않고 전부 제외해 부분 사실을 꾸미지 않는다.
+                        self.scan_capped = True
+                        return found
+                    for entry in sorted(entries, key=lambda entry: entry.name):
+                        try:
+                            self._visit(entry, directory, depth, pending, found)
+                        except OSError:
+                            self.scan_errors += 1
             except OSError:
+                self.scan_errors += 1
                 continue
-            for entry in entries:
-                scanned += 1
-                if scanned > MAX_SCANNED_ENTRIES:
-                    self.scan_capped = True
-                    return found
-                self._visit(entry, depth, pending, found)
         return found
 
-    def _visit(self, entry: os.DirEntry[str], depth: int, pending: list[tuple[Path, int]], found: list[str]) -> None:
+    def _visit(
+        self, entry: os.DirEntry[str], directory: str, depth: int, pending: list[tuple[str, int]], found: list[str]
+    ) -> None:
         """순회 항목 하나를 분류한다.
 
         Args:
             entry: 디렉터리 항목.
+            directory: 부모의 프로젝트 상대 경로.
             depth: 부모 깊이.
             pending: 더 들어갈 디렉터리 목록(수정한다).
             found: 발견한 파일 목록(수정한다).
         """
-        if entry.is_symlink():
-            self.skipped_links += 1
+        relative = PurePosixPath(directory, entry.name).as_posix()
+        if _is_link(entry.stat(follow_symlinks=False)):
+            self._record_link(relative)
             return
         if entry.is_dir(follow_symlinks=False):
             if entry.name.startswith(".") or entry.name in SKIPPED_DIRECTORIES:
@@ -163,9 +190,8 @@ class Project:
             if depth + 1 > MAX_SCAN_DEPTH:
                 self.scan_capped = True
                 return
-            pending.append((Path(entry.path), depth + 1))
+            pending.append((relative, depth + 1))
         elif entry.name.endswith(".py") and entry.is_file(follow_symlinks=False):
-            relative = Path(entry.path).relative_to(self.root).as_posix()
             if _is_encodable(relative):
                 found.append(relative)
             else:
@@ -182,7 +208,7 @@ class Project:
             디렉터리면 True.
         """
         try:
-            mode = os.lstat(self.root / relative).st_mode
+            mode = self._checked_stat(relative).st_mode
         except OSError:
             return False
         return stat.S_ISDIR(mode)
@@ -197,7 +223,7 @@ class Project:
             일반 파일이면 True.
         """
         try:
-            mode = os.lstat(self.root / relative).st_mode
+            mode = self._checked_stat(relative).st_mode
         except OSError:
             return False
         return stat.S_ISREG(mode)
@@ -212,10 +238,10 @@ class Project:
         Returns:
             내용(BOM 제거), 읽을 수 없으면 None.
         """
-        if not self.is_file(relative) or not _inside(self.root, relative):
+        if limit < 0:
             return None
         try:
-            data = (self.root / relative).read_bytes()[: limit + 1]
+            data = self._read_bytes(relative, limit)
         except OSError:
             return None
         if len(data) > limit:
@@ -257,10 +283,8 @@ class Project:
         Returns:
             파싱한 모듈 또는 실패.
         """
-        if not self.is_file(relative) or not _inside(self.root, relative):
-            return ReadFailure(relative, "unreadable or not a regular file")
         try:
-            data = (self.root / relative).read_bytes()[: MAX_SOURCE_BYTES + 1]
+            data = self._read_bytes(relative, MAX_SOURCE_BYTES)
         except OSError:
             return ReadFailure(relative, "unreadable file")
         if len(data) > MAX_SOURCE_BYTES:
@@ -283,6 +307,78 @@ class Project:
             is_package=PurePosixPath(relative).name == "__init__.py",
         )
 
+    def _record_link(self, relative: str) -> None:
+        """순회와 이름 해석에서 거부한 같은 링크를 중복 없이 센다."""
+        if relative not in self._skipped_link_paths:
+            self._skipped_link_paths.add(relative)
+            self.skipped_links += 1
+
+    def _checked_stat(self, relative: str) -> os.stat_result:
+        """루트부터 모든 경로 성분을 lstat해 링크·상위 경로·비디렉터리 부모를 거부한다."""
+        if not _inside(relative):
+            raise OSError("not a project-relative path")
+        path = self.root
+        parts = PurePosixPath(relative).parts
+        for index in range(len(parts) + 1):
+            info = path.lstat()
+            if _is_link(info):
+                self._record_link(PurePosixPath(*parts[:index]).as_posix())
+                raise OSError("symbolic link is not followed")
+            if index == len(parts):
+                return info
+            if not stat.S_ISDIR(info.st_mode):
+                raise OSError("parent is not a directory")
+            path /= parts[index]
+        raise AssertionError("path has a final component")
+
+    @contextmanager
+    def _open_directory(self, relative: str) -> Iterator[int | Path]:
+        """부모 핸들 기준 O_NOFOLLOW로 디렉터리를 연다. 미지원 환경은 경로를 재검사한다."""
+        expected = self._checked_stat(relative)
+        if not stat.S_ISDIR(expected.st_mode):
+            raise OSError("not a directory")
+        if not _HAS_DIR_FD:
+            yield self.root / relative
+            return
+        flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+        descriptor = os.open(self.root, flags)
+        try:
+            for part in PurePosixPath(relative).parts:
+                child = os.open(part, flags, dir_fd=descriptor)
+                os.close(descriptor)
+                descriptor = child
+            if not os.path.samestat(expected, os.fstat(descriptor)):
+                raise OSError("directory changed while opening")
+            yield descriptor
+        finally:
+            os.close(descriptor)
+
+    @contextmanager
+    def scan_directory(self, relative: str) -> Iterator[Iterator[os.DirEntry[str]]]:
+        """검증한 디렉터리만 열거하고 항목을 분류할 때까지 핸들을 유지한다."""
+        with self._open_directory(relative) as directory, os.scandir(directory) as entries:
+            yield entries
+
+    def _read_bytes(self, relative: str, limit: int) -> bytes:
+        """검증한 일반 파일 핸들에서만 제한된 바이트를 읽어 검사·열기 사이 링크 교체를 막는다."""
+        expected = self._checked_stat(relative)
+        if not stat.S_ISREG(expected.st_mode):
+            raise OSError("not a regular file")
+        path = PurePosixPath(relative)
+        flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0)
+        with self._open_directory(path.parent.as_posix()) as directory:
+            if isinstance(directory, int):
+                descriptor = os.open(path.name, flags, dir_fd=directory)
+            else:
+                descriptor = os.open(directory / path.name, flags)
+            with os.fdopen(descriptor, "rb") as source:
+                actual = os.fstat(source.fileno())
+                if not stat.S_ISREG(actual.st_mode) or not os.path.samestat(expected, actual):
+                    raise OSError("file changed while opening")
+                if not os.path.samestat(actual, self._checked_stat(relative)):
+                    raise OSError("path changed while opening")
+                return source.read(limit + 1)
+
     def module_name(self, relative: str) -> str:
         """파일 경로에서 모듈 이름을 만든다. 파일을 담은 가장 긴 모듈 루트를 기준으로 한다.
 
@@ -317,23 +413,36 @@ class Project:
         relative_parts = name.replace(".", "/")
         for root in self.module_roots:
             base = f"{root}/{relative_parts}" if root else relative_parts
-            for candidate in (f"{base}.py", f"{base}/__init__.py"):
+            # 같은 검색 루트에서는 일반 패키지가 같은 이름의 .py 모듈보다 우선한다.
+            # __init__.py 없는 namespace 디렉터리는 기존 일반 모듈을 가리지 않는다.
+            for candidate in (f"{base}/__init__.py", f"{base}.py"):
                 if self.is_file(candidate):
                     return candidate
         return None
 
 
-def _inside(root: Path, relative: str) -> bool:
-    """상대 경로가 `..` 없이 프로젝트 안을 가리키는지 확인한다.
+def _inside(relative: str) -> bool:
+    """플랫폼마다 다르게 해석될 경로와 `..`를 거부한다. 링크 검사는 별도로 한다.
 
     Args:
-        root: 프로젝트 루트.
         relative: 상대 경로.
 
     Returns:
         안이면 True.
     """
-    return ".." not in PurePosixPath(relative).parts and not PurePosixPath(relative).is_absolute()
+    return (
+        "\x00" not in relative
+        and "\\" not in relative
+        and ".." not in PurePosixPath(relative).parts
+        and not PurePosixPath(relative).is_absolute()
+        and not PureWindowsPath(relative).drive
+    )
+
+
+def _is_link(info: os.stat_result) -> bool:
+    """심볼릭 링크와 Windows 재분석 지점(디렉터리 junction 포함)을 거부한다."""
+    reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+    return stat.S_ISLNK(info.st_mode) or bool(getattr(info, "st_file_attributes", 0) & reparse_point)
 
 
 def _is_encodable(text: str) -> bool: