pytaut 0.1.0__tar.gz

pytaut-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: bash scripts/test.sh

pytaut-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: bash scripts/test.sh
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pytaut/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

pytaut-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.research/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+__pycache__/
+*.pyc
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+/docs/

pytaut-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing to taut
+
+Bug reports and rule proposals are welcome through GitHub Issues. A rule must describe a condition
+that can be determined reliably from code, rather than a subjective preference.
+
+Run the full verification suite before submitting a change:
+
+```bash
+bash scripts/test.sh
+```
+
+A new rule needs tests that demonstrate:
+
+- a violation is detected;
+- compliant code passes;
+- unrelated code zones remain unaffected; and
+- invalid configuration fails with a clear error.

pytaut-0.1.0/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.

pytaut-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,152 @@
+# 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/SECURITY.md

@@ -0,0 +1,6 @@
+# Security Policy
+
+Do not report vulnerabilities through a public Issue. Use GitHub private vulnerability reporting
+and include reproduction steps and the expected impact.
+
+Only the latest published version is currently supported with security fixes.

pytaut-0.1.0/pyproject.toml

@@ -0,0 +1,159 @@
+[project]
+name = "pytaut"
+version = "0.1.0"
+description = "Deterministic architecture policy checks for Python backends"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "TaeWoo Kim", email = "173425210+taewoo-dev@users.noreply.github.com" },
+]
+keywords = ["architecture", "linter", "policy", "python", "static-analysis"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://github.com/taewoo-dev/taut#readme"
+Issues = "https://github.com/taewoo-dev/taut/issues"
+Repository = "https://github.com/taewoo-dev/taut"
+
+[project.scripts]
+taut = "taut.cli:main"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.18",
+  "pytest>=8.4",
+  "pytest-cov>=6",
+  "pyright>=1.1.405",
+  "ruff>=0.12",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/taut"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["."]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["-q", "--tb=short", "--strict-markers", "-ra"]
+markers = [
+  "integration: checks multiple engine stages or the installed CLI",
+  "contract: checks a stable architecture or result contract",
+]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["taut"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 90
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+explicit_package_bases = true
+mypy_path = ["src"]
+files = ["src", "tests", "scripts"]
+exclude = ["^tests/fixtures/"]
+
+[tool.pyright]
+include = ["src", "tests", "scripts"]
+extraPaths = ["."]
+exclude = ["tests/fixtures"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+
+[tool.taut]
+strict = true
+include = ["src/*.py", "src/**/*.py"]
+source_roots = ["src"]
+
+[tool.taut.roles]
+domain = ["src/taut/domain/*.py", "src/taut/domain/**/*.py"]
+analysis = ["src/taut/analysis/*.py", "src/taut/analysis/**/*.py"]
+configuration = [
+  "src/taut/configuration/*.py",
+  "src/taut/configuration/**/*.py",
+]
+policy = ["src/taut/policy/*.py", "src/taut/policy/**/*.py"]
+finding_processing = [
+  "src/taut/finding_processing/*.py",
+  "src/taut/finding_processing/**/*.py",
+]
+incremental = ["src/taut/incremental/*.py", "src/taut/incremental/**/*.py"]
+loading = ["src/taut/loading/*.py", "src/taut/loading/**/*.py"]
+reporting = ["src/taut/reporting/*.py", "src/taut/reporting/**/*.py"]
+composition = ["src/taut/__init__.py", "src/taut/cli.py"]
+
+[tool.taut.allow]
+domain = ["domain"]
+analysis = ["domain", "analysis"]
+configuration = ["domain", "configuration"]
+policy = ["domain", "analysis", "configuration", "policy"]
+finding_processing = ["domain", "configuration", "finding_processing"]
+incremental = ["domain", "analysis", "policy", "incremental"]
+loading = ["domain", "analysis", "configuration", "loading"]
+reporting = ["domain", "reporting"]
+composition = [
+  "domain",
+  "analysis",
+  "configuration",
+  "policy",
+  "finding_processing",
+  "incremental",
+  "loading",
+  "reporting",
+  "composition",
+]
+
+[tool.taut.layers]
+service = ["policy"]
+contract = ["domain"]
+
+[tool.taut.external]
+logged_calls = ["httpx.AsyncClient", "httpx.Client"]
+wrappers = ["taut.external_call"]
+
+[tool.taut.enum]
+shared_modules = [
+  "taut.configuration.catalog",
+  "taut.domain.diagnostics",
+  "taut.domain.evaluations",
+  "taut.domain.facts",
+  "taut.domain.findings",
+  "taut.domain.issues",
+]
+uppercase_value_exceptions = ["taut.configuration.catalog.Effect"]

pytaut-0.1.0/scripts/__init__.py

@@ -0,0 +1 @@
+"""Repository verification helpers."""