pythograph 0.3.0__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. {pythograph-0.3.0 → pythograph-0.3.1}/CHANGELOG.md +28 -0
  2. {pythograph-0.3.0 → pythograph-0.3.1}/PKG-INFO +37 -8
  3. {pythograph-0.3.0 → pythograph-0.3.1}/README.ko.md +32 -4
  4. {pythograph-0.3.0 → pythograph-0.3.1}/README.md +35 -7
  5. {pythograph-0.3.0 → pythograph-0.3.1}/pyproject.toml +2 -1
  6. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/__init__.py +1 -1
  7. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/build.py +2 -0
  8. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/limitations.py +3 -10
  9. pythograph-0.3.1/src/pythograph/graph/source_diagnostics.py +265 -0
  10. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/command.py +7 -6
  11. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/apps.py +2 -16
  12. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/catalog.py +2 -17
  13. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/fields.py +3 -18
  14. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/queries.py +6 -5
  15. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/scope.py +14 -0
  16. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqlalchemy/queries.py +1 -1
  17. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqltext.py +8 -11
  18. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/classes.py +5 -21
  19. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/urlconf.py +41 -6
  20. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/evaluate.py +20 -0
  21. {pythograph-0.3.0 → pythograph-0.3.1}/.gitignore +0 -0
  22. {pythograph-0.3.0 → pythograph-0.3.1}/LICENSE +0 -0
  23. {pythograph-0.3.0 → pythograph-0.3.1}/docs/CHANGE-IMPACT.md +0 -0
  24. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/__main__.py +0 -0
  25. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/__init__.py +0 -0
  26. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/change_command.py +0 -0
  27. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/common.py +0 -0
  28. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/graph_commands.py +0 -0
  29. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/main.py +0 -0
  30. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/__init__.py +0 -0
  31. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/client_document.py +0 -0
  32. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/document.py +0 -0
  33. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/methods.py +0 -0
  34. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/order.py +0 -0
  35. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/persistence.py +0 -0
  36. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/scope.py +0 -0
  37. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/template.py +0 -0
  38. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/__init__.py +0 -0
  39. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/bound.py +0 -0
  40. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/calls.py +0 -0
  41. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/change.py +0 -0
  42. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/collect.py +0 -0
  43. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/document.py +0 -0
  44. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/exposure.py +0 -0
  45. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/flow.py +0 -0
  46. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/framework.py +0 -0
  47. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/framework_table.py +0 -0
  48. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/index.py +0 -0
  49. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/model.py +0 -0
  50. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/mro.py +0 -0
  51. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/revision.py +0 -0
  52. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/roots.py +0 -0
  53. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/scope.py +0 -0
  54. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/traversal.py +0 -0
  55. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/values.py +0 -0
  56. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/__init__.py +0 -0
  57. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/__init__.py +0 -0
  58. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/declarations.py +0 -0
  59. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/settings.py +0 -0
  60. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/location.py +0 -0
  61. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/model.py +0 -0
  62. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/names.py +0 -0
  63. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sql.py +0 -0
  64. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqlalchemy/__init__.py +0 -0
  65. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqlalchemy/catalog.py +0 -0
  66. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/py.typed +0 -0
  67. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/__init__.py +0 -0
  68. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/__init__.py +0 -0
  69. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/compose.py +0 -0
  70. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/constants.py +0 -0
  71. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/extract.py +0 -0
  72. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/formats.py +0 -0
  73. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/libraries.py +0 -0
  74. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/model.py +0 -0
  75. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/parts.py +0 -0
  76. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/wrappers.py +0 -0
  77. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/command.py +0 -0
  78. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/__init__.py +0 -0
  79. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/drf.py +0 -0
  80. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/extract.py +0 -0
  81. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/settings.py +0 -0
  82. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/views.py +0 -0
  83. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/flask/__init__.py +0 -0
  84. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/flask/extract.py +0 -0
  85. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/flask/rules.py +0 -0
  86. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/model.py +0 -0
  87. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/pattern.py +0 -0
  88. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/versions.py +0 -0
  89. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/__init__.py +0 -0
  90. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/bindings.py +0 -0
  91. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/inputs.py +0 -0
  92. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/project.py +0 -0
  93. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/symbols.py +0 -0
  94. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/syntax.py +0 -0
  95. {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/text.py +0 -0
@@ -4,6 +4,34 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.3.1] - 2026-11-03
8
+
9
+ - Preserve imported DRF router aliases and module attributes, while conditional or externally mutated router state stays opaque. Execute the vendored SQL relation conformance cases and include scripts in Ruff checks.
10
+
11
+ ### Fixed
12
+
13
+ - 다른 모듈에서 가져온 DRF 라우터의 `router.urls`를 정적으로 해석한다. import 이후의
14
+ 외부 등록 변경과 순환 import는 확정 경로로 추측하지 않고 기존 한계 보고를 유지한다.
15
+ - 그래프 파서 진단이 `requires-python`의 흔한 형식(`>=3.11,<4`, `~=3.11`, `>3.10`, `==3.11.*`)에서도 하한을 읽어
16
+ `runtime-below-minimum`·`minimum-not-newer`를 판정한다. 전에는 문자열 전체가 `>=숫자버전` 하나일 때만 읽고 나머지는
17
+ `not-evaluated`였다. 상한은 실행 버전과 비교하지 않는다. 상한이 하한과 겹치지 않아 만족할 수 없는 요구(`>=3.10,<3.9`),
18
+ 실행 버전이 `!=` 조건에 걸리는 경우, 사전 릴리스·epoch·로컬 버전처럼 읽지 않는 조건이 있는 경우는 계속
19
+ `not-evaluated`다. 상태 값 집합과 사실·`graphRevision`은 바뀌지 않는다.
20
+
21
+ - 그래프 누락 진단에 정점 대상·추가 테스트 문맥·전체 파싱 시도의 분모와 이유를 구분한
22
+ `statistics.sourceAnalysis`를 더한다. `unparsed-files:`와 `supplemental-test-files:`는 배타적인 범위이며
23
+ `source-budget:`는 두 범위와 겹칠 수 있는 실행 전체 예산 실패 수다. 기존 `unparsedFiles`·64 MiB 상한·그래프 사실과
24
+ `graphRevision`은 유지한다. 실제 파서 거부가 있으면 실행 Python과 정식 프로젝트 최소 버전을 함께 진단하며,
25
+ 새 문법을 소스 자체의 문법 오류로 단정하거나 미지원 런타임의 분석을 지원 완료로 판정하지 않는다.
26
+
27
+ ### Changed
28
+
29
+ - `schema`가 모듈마다 구문 트리를 한 번만 펼쳐 Django·SQLAlchemy 사용, SQL 텍스트, docstring·import 판독이 함께 쓴다.
30
+ 전에는 판독기마다 같은 트리를 따로 `ast.walk`해 사용 판독 단계에서 모듈 하나를 최대 일곱 번 훑었다
31
+ (netbox `schema` 중앙값 4.64 → 3.58 s, 최대 RSS 약 279 MiB로 같음). 출력은 같다.
32
+ - Python 3.14를 CI와 릴리스 검증(ubuntu)에 더하고 패키지 분류자에 `Programming Language :: Python :: 3.14`를 싣는다.
33
+ 분석 대상 코드는 실행 중인 인터프리터의 `ast`로 파싱하므로 3.14 문법을 쓰는 프로젝트는 3.14로 실행해야 한다.
34
+
7
35
  ## [0.3.0] - 2026-10-24
8
36
 
9
37
  기존 `impact <id>` 출력은 유지된다.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pythograph
3
- Version: 0.3.0
3
+ Version: 0.3.1
4
4
  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.
5
5
  Project-URL: Homepage, https://github.com/ictechgy/pythograph
6
6
  Project-URL: Repository, https://github.com/ictechgy/pythograph
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.10
22
22
  Classifier: Programming Language :: Python :: 3.11
23
23
  Classifier: Programming Language :: Python :: 3.12
24
24
  Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Programming Language :: Python :: 3.14
25
26
  Classifier: Topic :: Software Development :: Quality Assurance
26
27
  Classifier: Typing :: Typed
27
28
  Requires-Python: >=3.10
@@ -31,6 +32,11 @@ Description-Content-Type: text/markdown
31
32
 
32
33
  <img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph's blue tit mascot" width="112" height="112" align="right">
33
34
 
35
+ [![PyPI](https://img.shields.io/pypi/v/pythograph)](https://pypi.org/project/pythograph/)
36
+ [![Python versions](https://img.shields.io/pypi/pyversions/pythograph)](https://pypi.org/project/pythograph/)
37
+ [![CI](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml)
38
+ [![License: MIT](https://img.shields.io/pypi/l/pythograph)](https://github.com/ictechgy/pythograph/blob/main/LICENSE)
39
+
34
40
  [한국어](https://github.com/ictechgy/pythograph/blob/main/README.ko.md)
35
41
 
36
42
  Static facts for Python services (Django, Django REST framework, Flask, SQLAlchemy), emitted in the
@@ -76,10 +82,26 @@ pythograph --version
76
82
  ```
77
83
 
78
84
  To try unreleased changes, install from GitHub (`uv tool install git+https://github.com/ictechgy/pythograph`, or pin a
79
- release tag such as `@v0.1.0`). A wheel built from a checkout (`uv build`) installs the same way:
85
+ release tag such as `@v0.3.1`). A wheel built from a checkout (`uv build`) installs the same way:
80
86
  `uv tool install dist/pythograph-<version>-py3-none-any.whl`. The release steps are in
81
87
  [RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md) (Korean).
82
88
 
89
+ ## Quick start
90
+
91
+ Create a small synthetic Flask source file; the analyzer reads it without importing or running it. No Flask installation is required for this example.
92
+
93
+ ```sh
94
+ mkdir -p pythograph-demo
95
+ cat > pythograph-demo/app.py <<'PYTHON'
96
+ from flask import Flask
97
+ app = Flask(__name__)
98
+ @app.get('/items')
99
+ def items():
100
+ return []
101
+ PYTHON
102
+ pythograph routes --role server --framework flask --project pythograph-demo
103
+ ```
104
+
83
105
  ## `pythograph routes --role server`
84
106
 
85
107
  ```sh
@@ -129,7 +151,7 @@ Example (synthetic, compacted; the real output is key-sorted JSON with two-space
129
151
  "platform": "python",
130
152
  "roles": ["server"],
131
153
  "target": "http",
132
- "tool": { "name": "pythograph", "version": "0.2.0" },
154
+ "tool": { "name": "pythograph", "version": "<version>" },
133
155
  "version": 1
134
156
  }
135
157
  ```
@@ -370,9 +392,9 @@ directory) measured route precision against each framework's resolver, relation-
370
392
  isthmus, handler-to-relation reachability, unresolved-call reasons, and runtime; the results and the fixed issues are in
371
393
  [DOGFOOD.md](https://github.com/ictechgy/pythograph/blob/main/DOGFOOD.md) (Korean).
372
394
 
373
- The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `2954375` and locked in
374
- `conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (135: `template.grammar`,
375
- `template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, and 57 url-compose cases for query tails,
395
+ The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `1d6683a` and locked in
396
+ `conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (149: `template.grammar`,
397
+ `template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, 14 SQL relation cases, and 57 url-compose cases for query tails,
376
398
  interpolation, normalization, stripping, masking, the `rfc3986`/`httpx-base-url`/`aiohttp-base-url` joins, and wrapper
377
399
  argument binding); the `dispatch.validate` checker also runs on the routes golden output.
378
400
 
@@ -446,9 +468,16 @@ annotations (forward references such as `"Mapped[str]"` or `"Client | None"`) ar
446
468
  that cannot be parsed (including one with a NUL character) or that nests too deeply is treated as an unknown
447
469
  annotation.
448
470
 
471
+ Graph snapshots expose `statistics.sourceAnalysis`: separate file denominators, parse outcomes and reasons for graph
472
+ symbols, tests excluded from symbols but read as supplemental context, and all parse attempts. `unparsed-files:` and
473
+ `supplemental-test-files:` cover disjoint scopes; `source-budget:` is a run-wide total that can overlap both. Unrequested
474
+ tests are counted as not attempted. Actual parser syntax rejections also report the running Python and a bounded, static
475
+ reading of `[project].requires-python`. A newer declared minimum remains an environment blocker; parser rejection alone
476
+ cannot distinguish invalid syntax from syntax newer than the running Python. See [graph diagnostics](https://github.com/ictechgy/pythograph/blob/main/docs/GRAPH.md).
477
+
449
478
  One run parses at most 64 MiB of Python source in total, counting only the modules it parses successfully. A module
450
479
  that would push the total past this budget is not parsed and is reported like a file that fails to parse
451
- (`unparsed-files:` in graph output, `route-coverage:` or `route-call-coverage:` for routes, `unreadable-sources:` for
480
+ (`source-budget:` in graph output, `route-coverage:` or `route-call-coverage:` for routes, `unreadable-sources:` for
452
481
  schema) with the reason "the run's total parsed source would exceed its 64 MiB budget; pass a narrower --project";
453
482
  the command still succeeds with the other modules. Each command parses in a fixed order (path order, with modules
454
483
  reached through imports parsed when first needed), so the same input skips the same modules on every run. Parsed syntax
@@ -583,7 +612,7 @@ are checked while reading. These boundaries and explicit omissions are documente
583
612
  Captures use Git-selected inputs; `bound` assumes those selected sources form the whole program. Ignored
584
613
  runtime writers may therefore change ordinary graph results. Materialization rejects paths that alias on
585
614
  the destination filesystem instead of merging their identities.
586
- See [change analysis](docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
615
+ See [change analysis](https://github.com/ictechgy/pythograph/blob/main/docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
587
616
 
588
617
  ## License
589
618
 
@@ -2,6 +2,11 @@
2
2
 
3
3
  <img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph의 푸른박새 마스코트" width="112" height="112" align="right">
4
4
 
5
+ [![PyPI](https://img.shields.io/pypi/v/pythograph)](https://pypi.org/project/pythograph/)
6
+ [![Python versions](https://img.shields.io/pypi/pyversions/pythograph)](https://pypi.org/project/pythograph/)
7
+ [![CI](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml)
8
+ [![License: MIT](https://img.shields.io/pypi/l/pythograph)](https://github.com/ictechgy/pythograph/blob/main/LICENSE)
9
+
5
10
  [English](README.md)
6
11
 
7
12
  Python 서비스(Django, Django REST framework, Flask, SQLAlchemy)의 정적 사실을
@@ -44,9 +49,25 @@ pythograph --version
44
49
  ```
45
50
 
46
51
  아직 릴리스되지 않은 변경을 써 보려면 GitHub에서 설치한다(`uv tool install git+https://github.com/ictechgy/pythograph`, 또는
47
- `@v0.1.0` 같은 릴리스 태그로 고정). 체크아웃에서 빌드한 wheel(`uv build`)도 같은 방식이다:
52
+ `@v0.3.1` 같은 릴리스 태그로 고정). 체크아웃에서 빌드한 wheel(`uv build`)도 같은 방식이다:
48
53
  `uv tool install dist/pythograph-<버전>-py3-none-any.whl`. 릴리스 절차는 [RELEASING.md](RELEASING.md)에 있다.
49
54
 
55
+ ## 빠른 시작
56
+
57
+ 작은 합성 Flask 소스를 만든다. 분석기는 import하거나 실행하지 않고 읽으며, 이 예제에 Flask 설치는 필요하지 않다.
58
+
59
+ ```sh
60
+ mkdir -p pythograph-demo
61
+ cat > pythograph-demo/app.py <<'PYTHON'
62
+ from flask import Flask
63
+ app = Flask(__name__)
64
+ @app.get('/items')
65
+ def items():
66
+ return []
67
+ PYTHON
68
+ pythograph routes --role server --framework flask --project pythograph-demo
69
+ ```
70
+
50
71
  ## `pythograph routes --role server`
51
72
 
52
73
  ```sh
@@ -267,8 +288,8 @@ pythograph impact (reach와 같은 옵션)
267
288
  route 정밀도, schemagraph·isthmus 조인율, 핸들러 → relation-use 도달률, 미해석 호출 이유, 실행 시간을 잰 도그푸딩 결과와 고친
268
289
  문제는 [DOGFOOD.md](DOGFOOD.md)에 있다.
269
290
 
270
- isthmus 공유 적합성 벡터(`conformance/`, isthmus `2954375`에서 벤더링해 `conformance.lock`으로 고정)의 `producer`·
271
- `producer:pythograph` 사례 135건(`template.grammar`·`template.normalize`·`scope.validate`·`scope.applies`·`dispatch.validate`와
291
+ isthmus 공유 적합성 벡터(`conformance/`, isthmus `1d6683a`에서 벤더링해 `conformance.lock`으로 고정)의 `producer`·
292
+ `producer:pythograph` 사례 149건(`template.grammar`·`template.normalize`·`scope.validate`·`scope.applies`·`dispatch.validate`·SQL 관계 14건과
272
293
  query 꼬리·보간·정규화·strip·마스킹·`rfc3986`/`httpx-base-url`/`aiohttp-base-url` 결합·래퍼 인자 바인딩의 url-compose 57건)을
273
294
  100% 통과하고, `dispatch.validate` 검증기는 routes 출력 golden에도 적용한다.
274
295
 
@@ -331,8 +352,15 @@ graph `unparsed-files:`, routes `route-coverage:`, schema `unreadable-sources:`
331
352
  사슬 문자를 모두 셉니다). 문자열 주석(`"Mapped[str]"`·`"Client | None"` 같은 전방
332
353
  참조)도 같은 상한으로 파싱하며, 파싱할 수 없거나(NUL 문자 포함) 너무 깊은 주석은 모르는 주석으로 봅니다.
333
354
 
355
+ 그래프 스냅샷의 `statistics.sourceAnalysis`는 정점 대상, 정점에서 제외했지만 추가 문맥으로 읽은 테스트, 전체 파싱
356
+ 시도의 분모·결과·원인을 나눠 싣습니다. `unparsed-files:`와 `supplemental-test-files:`는 배타적인 범위이며,
357
+ `source-budget:`는 두 범위와 겹칠 수 있는 실행 전체 수입니다. 요청하지 않은 테스트는 미시도로 셉니다. 실제 파서의
358
+ 문법 거부가 있으면 실행 Python과 크기를 제한해 정적으로 읽은 `[project].requires-python`도 알립니다. 대상의 더 새
359
+ 최소 버전은 환경 차단으로 남습니다. 파서 거부만으로 소스 오류와 실행 Python보다 새 문법을 구분하지 않습니다.
360
+ 자세한 필드는 [그래프 진단](docs/GRAPH.md)에 있습니다.
361
+
334
362
  실행 하나가 파싱하는 파이썬 소스는 모두 합쳐 64 MiB까지입니다(파싱에 성공한 모듈만 셉니다). 합이 이 예산을 넘게 할
335
- 모듈은 파싱하지 않고, 파싱하지 못한 파일처럼 graph `unparsed-files:`, routes `route-coverage:`·`route-call-coverage:`,
363
+ 모듈은 파싱하지 않고, 파싱하지 못한 파일처럼 graph `source-budget:`, routes `route-coverage:`·`route-call-coverage:`,
336
364
  schema `unreadable-sources:` 한계에 "the run's total parsed source would exceed its 64 MiB budget; pass a narrower
337
365
  --project" 이유로 남깁니다. 명령은 나머지 모듈로 성공합니다. 명령마다 파싱 순서가 정해져 있어(경로 순, import로 닿은
338
366
  모듈은 처음 필요할 때) 같은 입력이면 실행마다 같은 모듈이 빠집니다. 파싱한 구문 트리는 이름 해석이 어느 모듈로든 돌아갈 수
@@ -2,6 +2,11 @@
2
2
 
3
3
  <img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph's blue tit mascot" width="112" height="112" align="right">
4
4
 
5
+ [![PyPI](https://img.shields.io/pypi/v/pythograph)](https://pypi.org/project/pythograph/)
6
+ [![Python versions](https://img.shields.io/pypi/pyversions/pythograph)](https://pypi.org/project/pythograph/)
7
+ [![CI](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml)
8
+ [![License: MIT](https://img.shields.io/pypi/l/pythograph)](https://github.com/ictechgy/pythograph/blob/main/LICENSE)
9
+
5
10
  [한국어](https://github.com/ictechgy/pythograph/blob/main/README.ko.md)
6
11
 
7
12
  Static facts for Python services (Django, Django REST framework, Flask, SQLAlchemy), emitted in the
@@ -47,10 +52,26 @@ pythograph --version
47
52
  ```
48
53
 
49
54
  To try unreleased changes, install from GitHub (`uv tool install git+https://github.com/ictechgy/pythograph`, or pin a
50
- release tag such as `@v0.1.0`). A wheel built from a checkout (`uv build`) installs the same way:
55
+ release tag such as `@v0.3.1`). A wheel built from a checkout (`uv build`) installs the same way:
51
56
  `uv tool install dist/pythograph-<version>-py3-none-any.whl`. The release steps are in
52
57
  [RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md) (Korean).
53
58
 
59
+ ## Quick start
60
+
61
+ Create a small synthetic Flask source file; the analyzer reads it without importing or running it. No Flask installation is required for this example.
62
+
63
+ ```sh
64
+ mkdir -p pythograph-demo
65
+ cat > pythograph-demo/app.py <<'PYTHON'
66
+ from flask import Flask
67
+ app = Flask(__name__)
68
+ @app.get('/items')
69
+ def items():
70
+ return []
71
+ PYTHON
72
+ pythograph routes --role server --framework flask --project pythograph-demo
73
+ ```
74
+
54
75
  ## `pythograph routes --role server`
55
76
 
56
77
  ```sh
@@ -100,7 +121,7 @@ Example (synthetic, compacted; the real output is key-sorted JSON with two-space
100
121
  "platform": "python",
101
122
  "roles": ["server"],
102
123
  "target": "http",
103
- "tool": { "name": "pythograph", "version": "0.2.0" },
124
+ "tool": { "name": "pythograph", "version": "<version>" },
104
125
  "version": 1
105
126
  }
106
127
  ```
@@ -341,9 +362,9 @@ directory) measured route precision against each framework's resolver, relation-
341
362
  isthmus, handler-to-relation reachability, unresolved-call reasons, and runtime; the results and the fixed issues are in
342
363
  [DOGFOOD.md](https://github.com/ictechgy/pythograph/blob/main/DOGFOOD.md) (Korean).
343
364
 
344
- The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `2954375` and locked in
345
- `conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (135: `template.grammar`,
346
- `template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, and 57 url-compose cases for query tails,
365
+ The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `1d6683a` and locked in
366
+ `conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (149: `template.grammar`,
367
+ `template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, 14 SQL relation cases, and 57 url-compose cases for query tails,
347
368
  interpolation, normalization, stripping, masking, the `rfc3986`/`httpx-base-url`/`aiohttp-base-url` joins, and wrapper
348
369
  argument binding); the `dispatch.validate` checker also runs on the routes golden output.
349
370
 
@@ -417,9 +438,16 @@ annotations (forward references such as `"Mapped[str]"` or `"Client | None"`) ar
417
438
  that cannot be parsed (including one with a NUL character) or that nests too deeply is treated as an unknown
418
439
  annotation.
419
440
 
441
+ Graph snapshots expose `statistics.sourceAnalysis`: separate file denominators, parse outcomes and reasons for graph
442
+ symbols, tests excluded from symbols but read as supplemental context, and all parse attempts. `unparsed-files:` and
443
+ `supplemental-test-files:` cover disjoint scopes; `source-budget:` is a run-wide total that can overlap both. Unrequested
444
+ tests are counted as not attempted. Actual parser syntax rejections also report the running Python and a bounded, static
445
+ reading of `[project].requires-python`. A newer declared minimum remains an environment blocker; parser rejection alone
446
+ cannot distinguish invalid syntax from syntax newer than the running Python. See [graph diagnostics](https://github.com/ictechgy/pythograph/blob/main/docs/GRAPH.md).
447
+
420
448
  One run parses at most 64 MiB of Python source in total, counting only the modules it parses successfully. A module
421
449
  that would push the total past this budget is not parsed and is reported like a file that fails to parse
422
- (`unparsed-files:` in graph output, `route-coverage:` or `route-call-coverage:` for routes, `unreadable-sources:` for
450
+ (`source-budget:` in graph output, `route-coverage:` or `route-call-coverage:` for routes, `unreadable-sources:` for
423
451
  schema) with the reason "the run's total parsed source would exceed its 64 MiB budget; pass a narrower --project";
424
452
  the command still succeeds with the other modules. Each command parses in a fixed order (path order, with modules
425
453
  reached through imports parsed when first needed), so the same input skips the same modules on every run. Parsed syntax
@@ -554,7 +582,7 @@ are checked while reading. These boundaries and explicit omissions are documente
554
582
  Captures use Git-selected inputs; `bound` assumes those selected sources form the whole program. Ignored
555
583
  runtime writers may therefore change ordinary graph results. Materialization rejects paths that alias on
556
584
  the destination filesystem instead of merging their identities.
557
- See [change analysis](docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
585
+ See [change analysis](https://github.com/ictechgy/pythograph/blob/main/docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
558
586
 
559
587
  ## License
560
588
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pythograph"
7
- version = "0.3.0"
7
+ version = "0.3.1"
8
8
  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."
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -23,6 +23,7 @@ classifiers = [
23
23
  "Programming Language :: Python :: 3.11",
24
24
  "Programming Language :: Python :: 3.12",
25
25
  "Programming Language :: Python :: 3.13",
26
+ "Programming Language :: Python :: 3.14",
26
27
  "Framework :: Django",
27
28
  "Framework :: Flask",
28
29
  "Topic :: Software Development :: Quality Assurance",
@@ -4,4 +4,4 @@
4
4
  """
5
5
 
6
6
  #: 배포 버전. `pyproject.toml`의 `project.version`과 같아야 한다(테스트가 대조한다).
7
- __version__ = "0.3.0"
7
+ __version__ = "0.3.1"
@@ -26,6 +26,7 @@ from pythograph.graph.index import Definition, DefinitionIndex
26
26
  from pythograph.graph.limitations import graph_limitations
27
27
  from pythograph.graph.model import EVIDENCE_ORDER, CallGraph, GraphEdge, GraphNode, NodeLocation
28
28
  from pythograph.graph.scope import Resolver
29
+ from pythograph.graph.source_diagnostics import source_statistics
29
30
  from pythograph.graph.values import ClassValue, FunctionValue
30
31
  from pythograph.source.project import Project
31
32
  from pythograph.source.symbols import SymbolTable
@@ -636,6 +637,7 @@ def _statistics(
636
637
  "boundDispatch": _bound_statistics(builder),
637
638
  "dynamicAttributeWrites": dynamic_writes,
638
639
  "unparsedFiles": builder.index.unparsed,
640
+ "sourceAnalysis": source_statistics(builder.project, builder.include_tests),
639
641
  "mroApproximated": len(builder.resolver.linearizer.approximated),
640
642
  }
641
643
 
@@ -9,7 +9,8 @@ from __future__ import annotations
9
9
  from typing import cast
10
10
 
11
11
  from pythograph.graph.model import DISPATCH_MODES
12
- from pythograph.source.project import Project, skipped_roots_reason, source_budget_reason
12
+ from pythograph.graph.source_diagnostics import source_lines
13
+ from pythograph.source.project import Project, skipped_roots_reason
13
14
 
14
15
  #: 프레임워크 표를 만든 설치본 버전이다.
15
16
  FRAMEWORK_VERSIONS = "Django 5.2.17, djangorestframework 3.18.1, Flask 3.1.3"
@@ -165,15 +166,7 @@ def _scan_lines(project: Project, statistics: dict[str, object]) -> list[str]:
165
166
  f"mro-approximated: {approximated} classes have an inconsistent or cyclic hierarchy; their method "
166
167
  "resolution order is approximated"
167
168
  )
168
- unparsed = cast(int, statistics.get("unparsedFiles", 0))
169
- if unparsed:
170
- lines.append(f"unparsed-files: {unparsed} Python files could not be read or parsed and have no symbols")
171
- if project.budget_skipped_modules:
172
- # 파싱 총량 예산 때문에 빠진 파일은 원인과 방향을 따로 알린다(위 수에는 이유가 없다).
173
- lines.append(
174
- f"unparsed-files: {project.budget_skipped_modules} Python files could not be analyzed: "
175
- + source_budget_reason()
176
- )
169
+ lines.extend(source_lines(project, statistics))
177
170
  if project.scan_capped or project.skipped_links or project.unencodable_names:
178
171
  lines.append(
179
172
  "scan-incomplete: the file walk stopped at a limit or skipped symbolic links or undecodable names; "
@@ -0,0 +1,265 @@
1
+ """파싱 결과를 바꾸지 않고 정점 범위·추가 테스트 흐름·실행 파서의 한계를 집계한다."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ import sys
7
+ from collections import Counter
8
+ from collections.abc import Collection, Mapping
9
+ from importlib import import_module
10
+ from typing import TypedDict, cast
11
+
12
+ from pythograph.source import project as project_module
13
+ from pythograph.source.project import Project, ReadFailure, SourceModule, is_test_path, source_budget_reason
14
+ from pythograph.source.text import is_contract_safe
15
+
16
+ #: 3.10도 실행 계약에 들어가므로, 그 런타임에서는 TOML 요구 판정을 명시적으로 생략한다.
17
+ _TOML = import_module("tomllib") if sys.version_info >= (3, 11) else None
18
+
19
+ #: 파서의 거부는 소스 자체의 문법 오류와 새 Python 문법을 구분하지 못한다.
20
+ SYNTAX_REASON = "syntax error or syntax newer than the running Python"
21
+
22
+ #: 메타데이터는 소스 예산을 쓰지 않지만 별도의 작은 읽기 상한을 둔다.
23
+ MAX_METADATA_BYTES = 64 * 1024
24
+
25
+ #: 쉼표로 이은 PEP 440 비교 조건 하나다. 숫자 세 자리까지의 최종 릴리스만 읽고(사전·사후·개발 릴리스, epoch, 로컬
26
+ #: 버전, `===`는 읽지 않는다) 끝 `.*`는 `==`·`!=`에서만 유효하다. 전체 호환 판정 대신 하한만 비교하려고 쓴다.
27
+ _CLAUSE = re.compile(r"(~=|==|!=|<=|>=|<|>)\s*([0-9]{1,4}(?:\.[0-9]{1,4}){0,2})(\.\*)?")
28
+
29
+ #: 버전 경계 하나: (세 자리로 채운 릴리스, 경계 자신을 포함하는지)다.
30
+ _Bound = tuple[tuple[int, ...], bool]
31
+
32
+ #: `!=` 제외 조건 하나: (적힌 릴리스, 끝 `.*` 접두사 비교인지)다.
33
+ _Exclusion = tuple[tuple[int, ...], bool]
34
+
35
+
36
+ class SourceCounts(TypedDict):
37
+ """한 범위의 분모와 배타적인 파싱 결과다. 실패 이유의 합은 unparsed와 같다."""
38
+
39
+ files: int
40
+ attempted: int
41
+ parsed: int
42
+ unparsed: int
43
+ notAttempted: int
44
+ failureReasons: dict[str, int]
45
+
46
+
47
+ def source_statistics(project: Project, include_tests: bool) -> dict[str, object]:
48
+ """이미 캐시한 결과만 집계한다. 진단 때문에 파일을 새로 파싱하거나 예산을 소비하지 않는다."""
49
+ outcomes = project.parsed_modules()
50
+ scanned = set(project.python_files())
51
+ graph = {path for path in scanned if include_tests or not is_test_path(path)}
52
+ all_attempts = _counts(outcomes.keys(), outcomes)
53
+ result: dict[str, object] = {
54
+ "scannedPythonFiles": len(scanned),
55
+ "includeTests": include_tests,
56
+ "graphFiles": _counts(graph, outcomes),
57
+ "supplementalTestFiles": _counts(scanned - graph, outcomes),
58
+ "outsideScanFiles": _counts(outcomes.keys() - scanned, outcomes),
59
+ "allParseAttempts": all_attempts,
60
+ "sourceBudget": {
61
+ "limitBytes": project_module.MAX_TOTAL_SOURCE_BYTES,
62
+ "parsedBytes": project.parsed_source_bytes,
63
+ "skippedFiles": project.budget_skipped_modules,
64
+ },
65
+ }
66
+ rejected = all_attempts["failureReasons"].get(SYNTAX_REASON, 0)
67
+ if rejected:
68
+ result["parser"] = _parser(project, rejected)
69
+ return result
70
+
71
+
72
+ def _counts(paths: Collection[str], outcomes: Mapping[str, SourceModule | ReadFailure]) -> SourceCounts:
73
+ """지정 경로의 성공·실패·미시도를 센다. 범위끼리 겹치지 않아도 전체 합계와는 겹친다."""
74
+ attempted = 0
75
+ failures: Counter[str] = Counter()
76
+ for path in paths:
77
+ outcome = outcomes.get(path)
78
+ if outcome is not None:
79
+ attempted += 1
80
+ if isinstance(outcome, ReadFailure):
81
+ failures[outcome.reason] += 1
82
+ unparsed = sum(failures.values())
83
+ return {
84
+ "files": len(paths),
85
+ "attempted": attempted,
86
+ "parsed": attempted - unparsed,
87
+ "unparsed": unparsed,
88
+ "notAttempted": len(paths) - attempted,
89
+ "failureReasons": dict(sorted(failures.items())),
90
+ }
91
+
92
+
93
+ def _parser(project: Project, rejected: int) -> dict[str, object]:
94
+ """실제 문법 거부가 있을 때 실행 파서와 읽을 수 있는 프로젝트 요구를 함께 싣는다."""
95
+ return {
96
+ "implementation": sys.implementation.name,
97
+ "version": ".".join(str(part) for part in sys.version_info[:3]),
98
+ "syntaxRejectedFiles": rejected,
99
+ **_requirement(project),
100
+ }
101
+
102
+
103
+ def _requirement(project: Project) -> dict[str, object]:
104
+ """작은 pyproject의 정식 project.requires-python만 읽는다. 분석 대상 코드를 실행하지 않는다."""
105
+ if not project.is_file("pyproject.toml"):
106
+ return {"requiresPythonStatus": "not-declared"}
107
+ text = project.read_text("pyproject.toml", MAX_METADATA_BYTES)
108
+ if text is None:
109
+ return {"requiresPythonStatus": "metadata-unreadable"}
110
+ if _TOML is None:
111
+ return {"requiresPythonStatus": "metadata-parser-unavailable"}
112
+ try:
113
+ metadata = _TOML.loads(text)
114
+ except (ValueError, RecursionError):
115
+ return {"requiresPythonStatus": "metadata-invalid"}
116
+ declaration = metadata.get("project", {})
117
+ if not isinstance(declaration, dict):
118
+ return {"requiresPythonStatus": "metadata-invalid"}
119
+ requirement = declaration.get("requires-python")
120
+ if requirement is None:
121
+ return {"requiresPythonStatus": "not-declared"}
122
+ if not isinstance(requirement, str) or len(requirement) > 256 or not is_contract_safe(requirement):
123
+ return {"requiresPythonStatus": "metadata-invalid"}
124
+ status = "not-evaluated"
125
+ if sys.version_info.releaselevel == "final":
126
+ major, minor, micro = sys.version_info[:3]
127
+ status = requirement_status(requirement, (major, minor, micro))
128
+ return {"requiresPython": requirement, "requiresPythonStatus": status}
129
+
130
+
131
+ def requirement_status(requirement: str, runtime: tuple[int, int, int]) -> str:
132
+ """`requires-python`의 하한만 실행 버전과 비교한다. 증명할 수 없는 형식은 판정하지 않는다.
133
+
134
+ 다른 조건은 허용 집합을 좁히기만 하므로, 실행 버전이 어느 하한에도 못 미치면 실제 최소 지원 버전에도 못 미친다.
135
+ 반대로 하한을 모두 넘어도 `!=` 조건에 걸리면 실제 최소 지원 버전(`>=3.8,!=3.8.*`이면 3.9)이 실행 버전보다
136
+ 새로울 수 있다. 상한은 최소 버전을 정하지 않으므로 실행 버전과 비교하지 않고(`minimum-not-newer`는 호환 판정이
137
+ 아니다), 어느 상한이 하한과 겹치지 않아 만족할 수 없는 요구인지만 본다. 그런 요구에는 최소 지원 버전이 없다.
138
+
139
+ Args:
140
+ requirement: 정식 메타데이터의 `requires-python` 문자열.
141
+ runtime: 실행 Python의 (major, minor, micro) 최종 릴리스 버전.
142
+
143
+ Returns:
144
+ `runtime-below-minimum`, `minimum-not-newer`, 또는 하한이 없거나 만족할 수 없거나 모르는 조건이 있으면
145
+ `not-evaluated`.
146
+ """
147
+ clauses = _clauses(requirement)
148
+ if clauses is None:
149
+ return "not-evaluated"
150
+ lower, upper, exclusions = clauses
151
+ if not lower or _unsatisfiable(lower, upper):
152
+ return "not-evaluated"
153
+ if any(runtime < version or (runtime == version and not closed) for version, closed in lower):
154
+ return "runtime-below-minimum"
155
+ excluded = any(
156
+ runtime[: len(release)] == release if prefix else runtime == _padded(release) for release, prefix in exclusions
157
+ )
158
+ return "not-evaluated" if excluded else "minimum-not-newer"
159
+
160
+
161
+ def _clauses(requirement: str) -> tuple[list[_Bound], list[_Bound], list[_Exclusion]] | None:
162
+ """조건을 하한·상한·`!=` 제외로 나눈다.
163
+
164
+ `==V`는 V 한 점이라 하한과 상한이 모두 V다. `==V.*`는 V로 시작하는 버전이고 `~=V`는 `>=V, ==V[:-1].*`이므로,
165
+ 둘 다 접두사의 마지막 자리를 하나 올린 값이 배타적 상한이다.
166
+
167
+ Args:
168
+ requirement: `requires-python` 문자열.
169
+
170
+ Returns:
171
+ (하한, 상한, 제외) 목록, 읽지 않는 형식이 하나라도 있으면 None.
172
+ """
173
+ lower: list[_Bound] = []
174
+ upper: list[_Bound] = []
175
+ exclusions: list[_Exclusion] = []
176
+ for text in requirement.split(","):
177
+ clause = _CLAUSE.fullmatch(text.strip())
178
+ if clause is None:
179
+ return None
180
+ operator, version, wildcard = clause.groups()
181
+ release = tuple(int(part) for part in version.split("."))
182
+ if (wildcard and operator not in ("==", "!=")) or (operator == "~=" and len(release) < 2):
183
+ return None
184
+ if operator == "!=":
185
+ exclusions.append((release, bool(wildcard)))
186
+ elif operator in (">=", ">"):
187
+ lower.append((_padded(release), operator == ">="))
188
+ elif operator in ("<=", "<"):
189
+ upper.append((_padded(release), operator == "<="))
190
+ elif operator == "==" and not wildcard:
191
+ lower.append((_padded(release), True))
192
+ upper.append((_padded(release), True))
193
+ else:
194
+ prefix = release if operator == "==" else release[:-1]
195
+ lower.append((_padded(release), True))
196
+ upper.append((_padded((*prefix[:-1], prefix[-1] + 1)), False))
197
+ return lower, upper, exclusions
198
+
199
+
200
+ def _unsatisfiable(lower: list[_Bound], upper: list[_Bound]) -> bool:
201
+ """어느 상한이 어느 하한보다 낮거나, 같은 점에서 한쪽이라도 그 점을 빼서 둘 다 만족할 버전이 없는지 본다."""
202
+ return any(
203
+ top < bottom or (top == bottom and not (top_closed and bottom_closed))
204
+ for top, top_closed in upper
205
+ for bottom, bottom_closed in lower
206
+ )
207
+
208
+
209
+ def _padded(release: tuple[int, ...]) -> tuple[int, ...]:
210
+ """PEP 440 비교처럼 빠진 뒷자리를 0으로 채워 세 자리로 맞춘다."""
211
+ return release + (0,) * (3 - len(release))
212
+
213
+
214
+ def source_lines(project: Project, statistics: dict[str, object]) -> list[str]:
215
+ """스냅샷과 순회에 같은 분모·원인 경계를 보존하는 한계를 만든다."""
216
+ analysis = cast(dict[str, object], statistics["sourceAnalysis"])
217
+ graph = cast(SourceCounts, analysis["graphFiles"])
218
+ supplemental = cast(SourceCounts, analysis["supplementalTestFiles"])
219
+ outside = cast(SourceCounts, analysis["outsideScanFiles"])
220
+ lines: list[str] = []
221
+ if graph["unparsed"]:
222
+ lines.append(
223
+ f"unparsed-files: {graph['unparsed']} of {graph['files']} graph-eligible Python files could not be "
224
+ f"read or parsed and have no symbols ({_reasons(graph)}); see graph statistics.sourceAnalysis"
225
+ )
226
+ if supplemental["unparsed"]:
227
+ lines.append(
228
+ f"supplemental-test-files: {supplemental['unparsed']} of {supplemental['files']} tests excluded from "
229
+ f"graph symbols could not be read or parsed for program-flow context ({_reasons(supplemental)}); "
230
+ "these files do not overlap graph-eligible omissions"
231
+ )
232
+ if outside["unparsed"]:
233
+ lines.append(
234
+ f"outside-scan-files: {outside['unparsed']} of {outside['files']} additional imported files outside "
235
+ f"the Python file walk could not be read or parsed ({_reasons(outside)})"
236
+ )
237
+ if project.budget_skipped_modules:
238
+ lines.append(
239
+ f"source-budget: {project.budget_skipped_modules} Python files could not be analyzed: "
240
+ + source_budget_reason()
241
+ + "; this run-wide total overlaps the scope failure counts in graph statistics.sourceAnalysis"
242
+ )
243
+ parser = cast(dict[str, object], analysis.get("parser", {}))
244
+ if parser:
245
+ lines.append(_parser_line(parser))
246
+ return lines
247
+
248
+
249
+ def _reasons(counts: SourceCounts) -> str:
250
+ """원인별 수를 안정된 순서로 표시한다."""
251
+ return "; ".join(f"{reason}: {count}" for reason, count in counts["failureReasons"].items())
252
+
253
+
254
+ def _parser_line(parser: dict[str, object]) -> str:
255
+ """파서 거부를 소스 문법 오류로 단정하지 않고 확인 가능한 환경 차이를 알린다."""
256
+ line = (
257
+ f"python-parser: {parser['syntaxRejectedFiles']} files were rejected by {parser['implementation']} "
258
+ f"{parser['version']} (syntax errors or syntax newer than this runtime)"
259
+ )
260
+ if parser.get("requiresPythonStatus") == "runtime-below-minimum":
261
+ line += (
262
+ f"; this runtime is below the declared minimum in pyproject.toml [project].requires-python "
263
+ f"{parser['requiresPython']}; rerun with a runtime satisfying the project requirement"
264
+ )
265
+ return line