pytaut 0.1.0__py3-none-any.whl

pytaut-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: pytaut
+Version: 0.1.0
+Summary: Deterministic architecture policy checks for Python backends
+Project-URL: Documentation, https://github.com/taewoo-dev/taut#readme
+Project-URL: Issues, https://github.com/taewoo-dev/taut/issues
+Project-URL: Repository, https://github.com/taewoo-dev/taut
+Author-email: TaeWoo Kim <173425210+taewoo-dev@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: architecture,linter,policy,python,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# taut
+
+`taut` makes hidden Python backend conventions explicit and blocks only violations it can
+determine reliably. The same source and configuration always produce the same result. It does
+not hard-code the names or directory layout of any company or service.
+
+The first PyPI release is being prepared. Until it is published, install directly from GitHub:
+
+```bash
+uv add --dev "pytaut @ git+https://github.com/taewoo-dev/taut.git"
+uv run taut check .
+```
+
+After the PyPI release, installation becomes:
+
+```bash
+uv add --dev pytaut
+```
+
+## Configuration
+
+Define repository roles and allowed dependencies in `pyproject.toml`. Strict mode is enabled by
+default, and the built-in maximum file length is 700 lines.
+
+```toml
+[tool.taut]
+strict = true
+source_roots = ["."]
+
+[tool.taut.roles]
+router = ["app/router/*.py", "app/router/**/*.py"]
+service = ["app/service/*.py", "app/service/**/*.py"]
+
+[tool.taut.allow]
+router = ["router", "service"]
+service = ["service"]
+
+[tool.taut.zones]
+test = ["tests/*.py", "tests/**/*.py"]
+
+[tool.taut.transaction]
+owner_roles = ["service"]
+session_providers = ["app.database.get_async_session"]
+```
+
+Built-in policies cover external calls, databases, security, DTOs, and schemas. Add only the
+repository-specific differences:
+
+```toml
+[tool.taut.external]
+modules = ["company_sdk"]
+wrappers = ["app.adapters.external_call"]
+
+[tool.taut.enum]
+shared_modules = ["app.core.enums"]
+```
+
+## Commands
+
+```bash
+taut config validate .
+taut check .
+taut check . --verbose
+taut check . --format json
+taut rules
+taut rules ASYNC001
+```
+
+To check another local repository:
+
+```bash
+uvx --no-cache --from /path/to/taut taut check /path/to/project
+```
+
+For a one-time audit that must not modify the target repository, provide an absolute path to an
+external configuration file:
+
+```bash
+taut check /path/to/project --config /path/to/audit-policy.toml
+```
+
+Role patterns and `source_roots` are resolved relative to the target project, not the
+configuration file. The legacy `.policy/policy.toml` format and explicit external configuration
+files remain supported.
+
+## Results
+
+The default terminal output prints one finding per line followed by the error and warning totals.
+Long findings wrap to the next indented line. Non-terminal output uses a width of 120 characters;
+override it with an option such as `--width 100`. Use `--verbose` only when you need related
+locations, remediation guidance, decision counts, and the decision digest.
+
+- Exit code `0`: no enforced violations
+- Exit code `1`: one or more enforced violations
+- Exit code `2`: invalid configuration, analysis failure, or an enforced rule that could not be
+  evaluated
+
+When an exception is unavoidable, suppress only the exact rule on the affected line:
+
+```python
+legacy_call()  # taut: ignore[ASYNC001]
+```
+
+An ignore without a rule ID, or with an unknown rule ID, is a configuration error. An ignore that
+does not suppress a real violation is reported as `IGNORE001`. File-wide ignores, violation
+baselines, and expiration management are intentionally unsupported.
+
+Raw SQL is not generally allowed. Application code should use SQLAlchemy expressions. A necessary
+raw query must pass through a registered shared wrapper configured with `raw_query_roles` and
+`raw_query_wrappers`. Fixed Model `server_default` expressions and partial Index predicates are
+allowed only within `schema_sql_roles` and `schema_sql_argument_names`.
+
+Registered raw-query calls must provide `name`, `statement`, and `parameters` as explicit keyword
+arguments. `name` and `statement` must be string literals, preventing SQL construction through
+f-strings or string concatenation.
+
+## Built-in rules
+
+With the default `strict = true`, `CAT001` is advisory and the other 47 rules are enforced.
+Individual rules cannot be disabled. Use `strict = false` before adoption to report every finding
+as a warning.
+
+| Group | Rules |
+|---|---|
+| Architecture | `ARCH000`-`002`, `BOUNDARY001`-`003`, `ENTRY001`, `SERVICE001`, `QUERY001`, `MODEL001`, `ADAPTER001`-`002`, `WIRING001`, `CONFIG001`, `DEPENDS001` |
+| Runtime safety | `TIME001`, `ASYNC001`, `RUNTIME001`, `IMPORT001`, `IMPORT002`, `SIZE001`, `SEC001` |
+| Database and transactions | `TX001`, `TX002`, `SESSION001`-`003`, `ORM001`, `ORM002`, `DB001`, `SQL001` |
+| External calls | `HTTP001`, `LOG001`, `CAT001` |
+| Data contracts | `DTO001`, `DTO002`, `SNAPSHOT001`, `SCHEMA001`-`003`, `API001`-`003`, `ENUM001`, `EXC001` |
+| Test boundaries | `TEST001`, `TEST002` |
+| Inline ignores | `IGNORE001` |
+
+Each rule declares whether it applies to `prod`, `test`, `migration`, or `script` code. Missing
+roles, dependency cycles, import placement, file size, dynamic execution, async safety, and
+security access are checked in every zone. API, DTO, database, and service-boundary rules apply to
+production code.
+
+An unregistered call that might have an external effect cannot be proven unsafe, so it is reported
+as a `CAT001` warning. After classifying the call, add it to the project effect catalog for precise
+enforcement.
+
+## Development
+
+```bash
+bash scripts/test.sh
+bash scripts/test.sh --only tests/unit/policy/test_builtin_rules.py -x
+```
+
+The full check runs the repository's own policy rules, Ruff, mypy strict, Pyright strict, pytest
+with at least 90% branch coverage, package builds, and an isolated wheel installation.
+
+See [`docs/README.md`](docs/README.md) for the current design documents.

pytaut-0.1.0.dist-info/RECORD

@@ -0,0 +1,88 @@
+taut/__init__.py,sha256=HnAKS-Y86m4B9dLgE-zEJW_T_BCWzrGPUqt20TKNLbs,117
+taut/cli.py,sha256=eIHnaVokfWeD5XbmIqUMMvzrFRkC9xbhA-74fb_f38I,11088
+taut/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+taut/analysis/__init__.py,sha256=vMBCVVPvRxyWpXh6eZfI96zHlBhT0FKOoKtYGP60ZyU,84
+taut/analysis/contracts.py,sha256=meMv6Y9hdOY4tJUYyx_tnDrXMjKGv069TeZS747RwjY,3253
+taut/analysis/module_analysis.py,sha256=g1wBRZdfdHxkHN7qKxbMQJA_cXHfZ5YYVCohC4fSk2o,1042
+taut/analysis/project_analyzer.py,sha256=LoOJkk9lmbzcepWJnIe6hdWEqcvg4DPm9SL_DibFnrA,2959
+taut/analysis/project_index.py,sha256=IlWHSw-MIv7520YCiuIBVGO9CrbDZ9c36iu5piJaGeo,4572
+taut/analysis/semantic_model.py,sha256=PTHs_--Z98-bxU-WJBVpAL5IEcuVLFO8vZ9W-d9tjZk,2280
+taut/analysis/python/__init__.py,sha256=gl5VU3-h8qWbCKoNnPJjQaU1dj6mddh751WFiEwB0wY,67
+taut/analysis/python/adapter.py,sha256=nrnXVa1POjK6131ePDEOErMb3DngUo0DdMJ37W2UUW8,16558
+taut/analysis/python/expression_summary.py,sha256=UttgAXYppatHOq8d9jHbUeJMnKLT4JgFGalkMzAqzao,6042
+taut/analysis/python/failed_analysis.py,sha256=RPLjne6XBKGta6zfKUeQtMWx5TbIReUXtNExC15joJc,1217
+taut/analysis/python/language_adapter.py,sha256=maaNu8E3uObjMWLS6O8k4O8YFOl6MJX_dyz_ArBDP20,3385
+taut/analysis/python/symbol_resolver.py,sha256=0wontLEU9JHB34qpVf92MS6hJ2B0Jwn64wvD7FqQkpY,8367
+taut/configuration/__init__.py,sha256=npHXSsBE-UiKtvuIDxHAhYykF119d6kRvBtAt78tqJU,96
+taut/configuration/catalog.py,sha256=DbNTmPuD4_xGQ7wxytLaQu4gt1VhEQXMQIleDsVlnxI,3081
+taut/configuration/effective_policy.py,sha256=PJcI99h3bmHavJRYIg3MuNk_bDIQMez5NdAdG2xA0Sg,18742
+taut/configuration/manifest.py,sha256=GFENSLIQ7NIZ7_S0Xm-kJMvivJkLW3J742H3bZigLIE,3964
+taut/configuration/model.py,sha256=QmfzAbOBmJq_xFlAm-jzDQfeB70a3M_RmvZ4U-ogOVU,1847
+taut/configuration/rule_standard.py,sha256=RFlaMJsKbw2wtafpcVkK9aIzG4SpwDYREfkrw1H4d68,1293
+taut/configuration/validation.py,sha256=bZxfxtK9wOuKBVIzE5GsLkJbJ0Y1S3egWKmfA7YXtGE,755
+taut/domain/__init__.py,sha256=Ee4ognEKqbz7uhFLFi090lGtYW3WixnN9-T5lMfT0ec,102
+taut/domain/diagnostics.py,sha256=vu0fMhV_C9dkT8G2QKgMK5f5fkh3Zuq4DAfQcwZ78ek,890
+taut/domain/evaluations.py,sha256=kPJ9JuSc8NPOrukfaCWiHTazU9wtwO0BeB7yZ0rJCbA,2388
+taut/domain/facts.py,sha256=zlnk7IaNnV_60WQPCVCwaXSLb5PqoBYPteOPucX7trE,11261
+taut/domain/findings.py,sha256=DXmtqa2eV0QUD1Dv_R03v1thLDDh555R9zRTMCS9HD4,2166
+taut/domain/frozen.py,sha256=l_L9QGpNZGe3rhGStmrcmA7YBA-ydkM2YboieB1HNyU,1517
+taut/domain/ids.py,sha256=WyT3Snhm44RBIvp0TlFRHsK9riTBGPe2x_Vn-V99vQ4,2081
+taut/domain/ignores.py,sha256=ETKQufcK1Gx96oiiPJbwNBYCjKJ-IP6vdn1NqocTaDY,545
+taut/domain/issues.py,sha256=KYYb0qcvQsIeMPSUApszJC9nktyCOcd-v-wnZfAPhR4,1004
+taut/domain/location.py,sha256=81N0kCUGFvfL4T5AQSJHJsXLdYy3j3mjzOJgZg5b5-E,2744
+taut/domain/provenance.py,sha256=tMwIijPJQxTVJX_ovxdHF9al-N0pUsCfW4j6u55VllI,615
+taut/domain/reports.py,sha256=K_Y-lkgraUJqcJcNB_AGZenKUmk-_rHaSzGFO-MzooI,2478
+taut/domain/snapshot.py,sha256=D14UnwFigZRb33zzdZ14nog-M7bfCZF8nycAIXxAo40,2524
+taut/finding_processing/__init__.py,sha256=zzAw-zCHHBIdoSRjBKP9-kWQq863vRAdd53fi183PGY,85
+taut/finding_processing/finding_processor.py,sha256=zktgKM5YkKIfzE35SY-ub1luzpxTufA4XI2t7ctY7fs,11040
+taut/finding_processing/report_builder.py,sha256=R5lK5z20bNMSLJP34K5E8PJ077jM_xF_dp3qJXIQDNM,1724
+taut/loading/__init__.py,sha256=3VmDcvGO8Lg23_qHTvi9pu7YFghN3weLLPyVg6HREOc,92
+taut/loading/boundary_extension_schema.py,sha256=Sh0Sin23Jt3soO9jvFgHaTcbXKgfYBHn4E6HPqrBbss,1260
+taut/loading/builtin_catalog.py,sha256=G3akQ-j0XNkW9HJwP2MO4j8UONW5Kc6-FxpQVbzZgM8,2178
+taut/loading/code_conventions.py,sha256=x6ZjcljlabiGsA6u5oTmPL7n6R3rl_MBIgRyVzUKkcg,5398
+taut/loading/config_loader.py,sha256=AzPtoZOfOrNLKc7xxVRoCDRJZENQvkqZ5rs5pRiVlkk,20067
+taut/loading/configuration_document.py,sha256=2MrtZZtL92vfg5gHzPCRXfjz39LCZtBVn0nG4g0EGPg,7743
+taut/loading/default_configuration.py,sha256=HnCwTUMBiOhtAQnBqLaP7bCYOQ3qZHQ-vwN54Y0rReM,2271
+taut/loading/errors.py,sha256=0pW0tXm7pMwyFG8iFMa5BQfEgAYDAJsgw_RRBs8lTsE,46
+taut/loading/inline_ignores.py,sha256=zZto8e4ZlPGVwdQIDDbRVxUrQqTKP8LPEnaNhwPlU2k,3066
+taut/loading/source_discovery.py,sha256=o8EmqhDrP97NwkL7Z--Q-Vsv4hQJal6QtfmkwwsNS0I,6002
+taut/policy/__init__.py,sha256=B9COZ5C-YzbssYbmCU9kUf-e9aEYle_xs68fCwuYO7k,89
+taut/policy/context.py,sha256=QjS4XCfHkLyOj3nhZdommCFcghA0ak6S4UVQUuG2f_c,1436
+taut/policy/decision_digest.py,sha256=-96HZRFjsop8giUeHxx23-HdzCZddSsq7Czv5qCAZ1g,999
+taut/policy/engine.py,sha256=DFaFXGt2BtNWEckbZ3CrRJfqSBMXJMmvbbQ8bE1Vde4,7465
+taut/policy/indexes.py,sha256=jb0IJUeELEorWuCz22TfYMJgAykRM0-qq5S769o-YP8,3525
+taut/policy/registry.py,sha256=KvDdrtYoWe6cjtqrL_x5yqrcO9CJUPmi3WA4pXrHmso,969
+taut/policy/rule.py,sha256=i4Cs8ol4OkdIINUv5zulvA0J23kPqUmOs7OKLJH2oqY,2591
+taut/policy/scheduler.py,sha256=iqZ6aHthR2XkEM7Me7jddruH5o9uFU9yi6eRHF49wnQ,2179
+taut/policy/rules/__init__.py,sha256=QJxHOyfZ4QsSCb0b5RjRhzvi0ZfVgbm37wCCJ7EgsbM,4019
+taut/policy/rules/api_contracts.py,sha256=_yLrkGs3WIh9URw99-jUTUegLjRxIWCwyknMON1y4qA,19021
+taut/policy/rules/architecture.py,sha256=kDxxGxSTPE52ddWeG0VZmyO8Kkj3TQ6NajS3nNJKAPc,6226
+taut/policy/rules/async_safety.py,sha256=NEbAhEEgSRWnxidbjFbTVLh-PqGb8Yhingy63blrBxI,3291
+taut/policy/rules/boundary.py,sha256=AcF9g-baLVgSCSuP_gq-E8pUaiYncJl_wzyq3hvayLQ,6193
+taut/policy/rules/catalog_coverage.py,sha256=A257BUdlRbIVAk38QcWYOJHWbDB84oTG8dUqtrU-_RU,2902
+taut/policy/rules/classification.py,sha256=Aa-pMVDeYZikoA0UP7e4jjulUlxcyTZRQWV0q_hALaE,2389
+taut/policy/rules/construction_boundaries.py,sha256=_T03ZpAS0Q2SfKyKwPmd06TkaNr0Oz9wy0vjWGwfGEw,7803
+taut/policy/rules/conventions.py,sha256=pWRjjSfaKwDL9nPJVbvcyeBior5a8ls2_K3zhjHyXrE,6150
+taut/policy/rules/enums.py,sha256=_HjDtVqxyq3W2CD0dbm0RWg_JV3M2oZvligGI3eugwA,7790
+taut/policy/rules/exceptions.py,sha256=8G4MVyhm0ci2LLrokzxxLsoZ_PFXLRdfuLQxhp7K1tU,9317
+taut/policy/rules/external_calls.py,sha256=q28dQOXlfPrxnmcrXt_hsj-i-l4140DfWyjy14OfMGE,5583
+taut/policy/rules/helpers.py,sha256=s1IsXcUUhEZJJuQLG8UqIIGixeWEeKQM6CPOdvua_8o,1386
+taut/policy/rules/ignore_audit.py,sha256=KvZ5S2D6DwKxRR-b3lQrXYEY8ZVYPm0Vikl5P8sc8cY,1486
+taut/policy/rules/layer_boundaries.py,sha256=skOAI9NIqm981OEZHdGb8ZUlO8T1VsT8qVSbn-dJNo8,17201
+taut/policy/rules/model_shapes.py,sha256=oR4Svg4VEwqB-_ckk-5ExSkJrVTJ_TFa26wjTLbKNWU,13919
+taut/policy/rules/persistence.py,sha256=Y7RE25YE6ZJKXfYObTa0FzLO4S2_StabYr1RO1hrP5E,14860
+taut/policy/rules/responsibility_boundaries.py,sha256=jh_77h7-2DXyOreNHnZxNWcqxIVIn8y4Ce8GLxUsa1w,9009
+taut/policy/rules/runtime_safety.py,sha256=q9VW24VnOApTPAyrC7c0xXZIF9n3Q8maGQzyVa7u-pU,6934
+taut/policy/rules/security.py,sha256=VxcDU7qubZiF1b-tEWCSJ9vKwWHl-UPpg9rstDVsLBc,5245
+taut/policy/rules/session.py,sha256=rD91qGaD1KXyM5z0PNK7ae9rJkLiRZEp1_WNVLNy0Ow,8614
+taut/policy/rules/test_boundaries.py,sha256=QrX9s4c2Z35kXgj2tt3dlDqb_LEKm80XqwPKPc-Y6yY,4567
+taut/policy/rules/time_access.py,sha256=UM-5qkBgVcLkMoZy8G8zdCqCM0u6ZxdancaKTGfk7_c,3810
+taut/policy/rules/transaction.py,sha256=rkYfQOrssp38HWb4T_5LN3bQ2W5Y5AMVGOhMX21t9aQ,4794
+taut/reporting/__init__.py,sha256=KZxYW1rOm_idC3mb9KDNPVLcxRvC7ZejFHrgEoxOqr0,82
+taut/reporting/json.py,sha256=VisbIGAvy_0_V1IpYyeBVnct4Zouw4HKBP5uMftElhc,4446
+taut/reporting/text.py,sha256=sTivtti4r9guuK4ZapsGdwkGQXB2jQFrJLmLKcNe2xA,7188
+pytaut-0.1.0.dist-info/METADATA,sha256=A12m5V0Wp9bqVwPwS6HjCDV2dZDc1ReF0v-I4fEtiLk,6355
+pytaut-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pytaut-0.1.0.dist-info/entry_points.txt,sha256=XmqwEA_0kKek9F2umLrcVkSAGv5KDfNDkQgaVwnY_68,39
+pytaut-0.1.0.dist-info/licenses/LICENSE,sha256=GGKppGXt0fZTXrHpv0D5k0wXwExUBY2uSSmYZyGzRrs,1067
+pytaut-0.1.0.dist-info/RECORD,,

pytaut-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytaut-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+taut = taut.cli:main

pytaut-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TaeWoo Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taut/__init__.py

@@ -0,0 +1,5 @@
+"""Deterministic policy checks for Python backend architecture."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

taut/analysis/__init__.py

@@ -0,0 +1,3 @@
+"""Source analysis and immutable snapshot construction."""
+
+__all__: list[str] = []

taut/analysis/contracts.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from taut.domain.facts import ModuleFacts, SourceKind
+from taut.domain.frozen import FrozenMap
+from taut.domain.ids import ModuleId, SymbolId
+from taut.domain.issues import EngineIssue
+from taut.domain.location import ProjectPath
+
+
+@dataclass(frozen=True, order=True)
+class ProjectRoot:
+    value: Path
+
+    def __post_init__(self) -> None:
+        if not self.value.is_absolute():
+            raise ValueError("project root must be an absolute path")
+
+
+@dataclass(frozen=True, order=True)
+class LanguageSettings:
+    language: str = "python"
+    target_version: str = "3.12"
+
+
+@dataclass(frozen=True, order=True)
+class ContextManagerProvider:
+    symbol: SymbolId
+    item_type: SymbolId
+
+
+@dataclass(frozen=True, order=True)
+class ResolverSettings:
+    source_roots: tuple[ProjectPath, ...] = (ProjectPath("."),)
+    context_manager_providers: tuple[ContextManagerProvider, ...] = ()
+
+    def __post_init__(self) -> None:
+        symbols = tuple(provider.symbol for provider in self.context_manager_providers)
+        if len(symbols) != len(set(symbols)):
+            raise ValueError("context manager provider symbols must be unique")
+        if self.context_manager_providers != tuple(sorted(self.context_manager_providers)):
+            raise ValueError("context manager providers must be sorted")
+
+
+@dataclass(frozen=True, order=True)
+class SourceInput:
+    path: ProjectPath
+    module_id: ModuleId
+    kind: SourceKind
+    is_policy_target: bool
+    is_package: bool
+    content: str
+    content_hash: str
+
+    def __post_init__(self) -> None:
+        if len(self.content_hash) != 64:
+            raise ValueError("source content hash must be a sha256 digest")
+
+
+@dataclass(frozen=True)
+class AnalysisRequest:
+    project_root: ProjectRoot
+    sources: tuple[SourceInput, ...]
+    language: LanguageSettings
+    resolver: ResolverSettings
+    adapter_versions: FrozenMap[str, str]
+
+    def __post_init__(self) -> None:
+        identities = tuple(source.module_id for source in self.sources)
+        if len(identities) != len(set(identities)):
+            raise ValueError("analysis request contains duplicate module ids")
+        paths = tuple(source.path.value.casefold() for source in self.sources)
+        if len(paths) != len(set(paths)):
+            raise ValueError("analysis request contains duplicate or case-conflicting paths")
+        if self.sources != tuple(sorted(self.sources, key=lambda source: source.path.value)):
+            raise ValueError("analysis sources must be sorted by project path")
+
+
+@dataclass(frozen=True, order=True)
+class AdapterIdentity:
+    name: str
+    version: str
+
+
+@dataclass(frozen=True)
+class ModuleAnalysisResult:
+    facts: ModuleFacts
+    issues: tuple[EngineIssue, ...]
+
+
+class LanguageAdapter(Protocol):
+    identity: AdapterIdentity
+
+    def analyze_module(
+        self,
+        source: SourceInput,
+        resolver: ResolverSettings | None = None,
+    ) -> ModuleAnalysisResult: ...
+
+    def analyze_modules(
+        self,
+        sources: tuple[SourceInput, ...],
+        resolver: ResolverSettings,
+        workers: int,
+    ) -> tuple[ModuleAnalysisResult, ...]: ...

taut/analysis/module_analysis.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from taut.domain.facts import AnalysisStage
+
+_NEXT_STAGE = {
+    AnalysisStage.DISCOVERED: AnalysisStage.PARSED,
+    AnalysisStage.PARSED: AnalysisStage.INDEXED,
+    AnalysisStage.INDEXED: AnalysisStage.RESOLVED,
+    AnalysisStage.RESOLVED: AnalysisStage.FACTS_READY,
+}
+
+
+@dataclass
+class ModuleAnalysis:
+    """Mutable analysis lifecycle. This value never leaves the analyzer."""
+
+    stage: AnalysisStage = AnalysisStage.DISCOVERED
+
+    def advance(self, stage: AnalysisStage) -> None:
+        if self.stage is AnalysisStage.FAILED:
+            raise ValueError("failed analysis cannot advance")
+        if _NEXT_STAGE.get(self.stage) is not stage:
+            raise ValueError(f"cannot move analysis from {self.stage.value} to {stage.value}")
+        self.stage = stage
+
+    def fail(self) -> None:
+        if self.stage is AnalysisStage.FACTS_READY:
+            raise ValueError("completed analysis cannot be marked failed")
+        self.stage = AnalysisStage.FAILED

taut/analysis/project_analyzer.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import hashlib
+import json
+
+from taut.analysis.contracts import AnalysisRequest, LanguageAdapter
+from taut.analysis.project_index import build_project_index
+from taut.domain.facts import CompletenessState, ModuleFacts
+from taut.domain.frozen import FrozenMap
+from taut.domain.ids import SnapshotId
+from taut.domain.issues import EngineIssue
+from taut.domain.snapshot import (
+    AnalysisCoverage,
+    AnalysisInputDigest,
+    AnalysisSnapshot,
+)
+
+
+class ProjectAnalyzer:
+    def __init__(self, adapter: LanguageAdapter) -> None:
+        self._adapter = adapter
+
+    def analyze(self, request: AnalysisRequest, *, workers: int = 1) -> AnalysisSnapshot:
+        if workers < 1:
+            raise ValueError("analysis workers must be positive")
+        modules: list[ModuleFacts] = []
+        issues: list[EngineIssue] = []
+        results = self._adapter.analyze_modules(request.sources, request.resolver, workers)
+        for result in results:
+            modules.append(result.facts)
+            issues.extend(result.issues)
+
+        module_map = FrozenMap((facts.module.id, facts) for facts in modules)
+        project = build_project_index(modules)
+        states = tuple(facts.completeness.state for facts in modules)
+        coverage = AnalysisCoverage(
+            requested_sources=len(request.sources),
+            complete_modules=states.count(CompletenessState.COMPLETE),
+            partial_modules=states.count(CompletenessState.PARTIAL),
+            failed_modules=states.count(CompletenessState.FAILED),
+        )
+        digest = _analysis_digest(request)
+        return AnalysisSnapshot(
+            id=SnapshotId(digest),
+            inputs=AnalysisInputDigest(digest),
+            modules=module_map,
+            project=project,
+            capabilities=FrozenMap(),
+            coverage=coverage,
+            issues=tuple(issues),
+        )
+
+
+def _analysis_digest(request: AnalysisRequest) -> str:
+    payload = {
+        "sources": [
+            {
+                "path": source.path.value,
+                "module": source.module_id.value,
+                "kind": source.kind.value,
+                "target": source.is_policy_target,
+                "hash": source.content_hash,
+            }
+            for source in request.sources
+        ],
+        "language": {
+            "name": request.language.language,
+            "target_version": request.language.target_version,
+        },
+        "resolver": {
+            "source_roots": [root.value for root in request.resolver.source_roots],
+            "context_manager_providers": [
+                (provider.symbol.value, provider.item_type.value)
+                for provider in request.resolver.context_manager_providers
+            ],
+        },
+        "adapters": list(request.adapter_versions.items()),
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()

taut/analysis/project_index.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from taut.domain.facts import (
+    ImportCycle,
+    ModuleFacts,
+    ProjectIndex,
+    UnresolvedImport,
+)
+from taut.domain.frozen import FrozenMap
+from taut.domain.ids import ModuleId
+
+
+def build_project_index(modules: Iterable[ModuleFacts]) -> ProjectIndex:
+    module_list = tuple(sorted(modules, key=lambda facts: facts.module.id))
+    module_ids = frozenset(facts.module.id for facts in module_list)
+    modules_by_name = {module_id.value: module_id for module_id in module_ids}
+    internal_roots = frozenset(module_id.value.split(".")[0] for module_id in module_ids)
+    imports: dict[ModuleId, set[ModuleId]] = {module_id: set() for module_id in module_ids}
+    unresolved: list[UnresolvedImport] = []
+
+    for facts in module_list:
+        for import_fact in facts.imports:
+            target = _resolve_internal_import(
+                import_fact.imported_name,
+                import_fact.imported_module_name,
+                modules_by_name,
+            )
+            if target is not None:
+                imports[facts.module.id].add(target)
+                continue
+            root = import_fact.imported_module_name.split(".")[0]
+            possibly_internal = import_fact.relative_level > 0 or root in internal_roots
+            if possibly_internal:
+                unresolved.append(
+                    UnresolvedImport(
+                        importer=facts.module.id,
+                        written_name=import_fact.imported_name,
+                        location=import_fact.location,
+                        reason="프로젝트 내부 모듈로 연결하지 못했습니다.",
+                    )
+                )
+
+    frozen_imports = FrozenMap(
+        (source, tuple(sorted(targets))) for source, targets in imports.items()
+    )
+    reverse: dict[ModuleId, set[ModuleId]] = {module_id: set() for module_id in module_ids}
+    for source, targets in imports.items():
+        for target in targets:
+            reverse[target].add(source)
+    frozen_reverse = FrozenMap(
+        (target, tuple(sorted(sources))) for target, sources in reverse.items()
+    )
+    cycles = _find_cycles(frozen_imports)
+    return ProjectIndex(
+        imports=frozen_imports,
+        imported_by=frozen_reverse,
+        unresolved_imports=tuple(
+            sorted(
+                unresolved,
+                key=lambda item: (
+                    item.location.path.value,
+                    item.location.start_line,
+                    item.location.start_column,
+                    item.written_name,
+                ),
+            )
+        ),
+        cycles=cycles,
+    )
+
+
+def _resolve_internal_import(
+    imported_name: str,
+    imported_module_name: str,
+    modules_by_name: dict[str, ModuleId],
+) -> ModuleId | None:
+    candidates = (imported_name, imported_module_name)
+    for candidate in candidates:
+        current = candidate
+        while current:
+            module_id = modules_by_name.get(current)
+            if module_id is not None:
+                return module_id
+            current = current.rpartition(".")[0]
+    return None
+
+
+def _find_cycles(
+    graph: FrozenMap[ModuleId, tuple[ModuleId, ...]],
+) -> tuple[ImportCycle, ...]:
+    index = 0
+    stack: list[ModuleId] = []
+    on_stack: set[ModuleId] = set()
+    indexes: dict[ModuleId, int] = {}
+    low_links: dict[ModuleId, int] = {}
+    components: list[tuple[ModuleId, ...]] = []
+
+    def visit(node: ModuleId) -> None:
+        nonlocal index
+        indexes[node] = index
+        low_links[node] = index
+        index += 1
+        stack.append(node)
+        on_stack.add(node)
+
+        for target in graph[node]:
+            if target not in indexes:
+                visit(target)
+                low_links[node] = min(low_links[node], low_links[target])
+            elif target in on_stack:
+                low_links[node] = min(low_links[node], indexes[target])
+
+        if low_links[node] != indexes[node]:
+            return
+        component: list[ModuleId] = []
+        while True:
+            member = stack.pop()
+            on_stack.remove(member)
+            component.append(member)
+            if member == node:
+                break
+        ordered = tuple(sorted(component))
+        if len(ordered) > 1 or (len(ordered) == 1 and ordered[0] in graph[ordered[0]]):
+            components.append(ordered)
+
+    for module_id in graph:
+        if module_id not in indexes:
+            visit(module_id)
+
+    return tuple(ImportCycle(component) for component in sorted(components))

taut/analysis/python/__init__.py

@@ -0,0 +1,3 @@
+"""Python stdlib-ast language adapter."""
+
+__all__: list[str] = []