Metadata-Version: 2.4
Name: scienith-openapi-contract-tooling
Version: 0.2.0
Summary: Reusable OpenAPI contract generation tooling for Scienith systems.
Author: Scienith
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: datamodel-code-generator<1,>=0.27

# scienith-openapi-contract-tooling

Scienith reusable OpenAPI contract tooling. This package is intended to replace per-system OpenAPI generation scripts after golden-output compatibility is proven.

## Install

From a private PyPI source:

```bash
pipx install scienith-openapi-contract-tooling
scienith-contract --help
```

`pip install scienith-openapi-contract-tooling` remains supported for Python environments that import or wrap the tooling. `pipx install` is the preferred CLI installation path because it isolates the command runtime from project virtual environments.

## Local Development

Use this project directory's own virtual environment. Do not install development dependencies into a business-system venv.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip build
python -m pip install -e .
python -m compileall src
python -m unittest discover -s tests
python -m build
python -m pip install --force-reinstall dist/*.whl
scienith-contract --help
```

## CLI Surface

```bash
scienith-contract --help
scienith-contract build --help
scienith-contract build all --help
scienith-contract openapi --help
scienith-contract openapi views --help
scienith-contract openapi uml --help
scienith-contract openapi redoc --help
scienith-contract generate --help
scienith-contract generate python-models --help
scienith-contract generate swift-models --help
scienith-contract generate ts-types --help
scienith-contract generate zod-ts --help
scienith-contract generate msw-handlers --help
```

The package provides both single-artifact OpenAPI generation commands and profile-driven full-system generation via `contract-tooling.yaml`. See `docs/contract-tooling-yaml.md`.

The Swift target is a deterministic, repository-owned emitter for an explicit OpenAPI 3.1 subset. It generates `Codable`, `Equatable`, and `Sendable` contract types plus recursive `JSONValue` and strict raw-JSON validation. Closed objects reject unknown properties and preserve the difference between a missing required nullable property and a present `null`. String length, numeric range, array size/uniqueness, UUID, date, and date-time constraints are enforced while decoding and encoding; unsupported validation keywords fail generation. Unsupported or ambiguous schemas fail with a schema path; the tool does not silently fall back to `[String: Any]` or claim arbitrary OpenAPI compatibility.

## Private Registry Configuration

Contract-package profiles can preserve an existing Python consumer API through
`python_model_options`. Supported boolean options are `snake_case_field`,
`strict_nullable`, `field_constraints`, `capitalise_enum_members`,
`use_standard_collections`, and `use_union_operator`; `extra_fields` accepts
`allow`, `ignore`, or `forbid`. Unknown options fail instead of being ignored.
`ts_default_non_nullable: false` preserves optional properties with defaults in
TypeScript input models. Omitting these settings retains existing generator defaults.

CI/CD must read private source configuration from GitHub organization-level Secrets/Variables only:

- `SCIENITH_PRIVATE_NETRC`: required secret, written to `~/.netrc`.
- `SCIENITH_PRIVATE_NPMRC`: required secret when npm/private JS packages are needed, written to `~/.npmrc`.
- `SCIENITH_PRIVATE_PYPI_SIMPLE_URL`: required variable or secret, used as pip `index-url`.
- `SCIENITH_PRIVATE_PYPI_PUBLISH_URL`: optional variable or secret. If missing, CI may derive it from `SCIENITH_PRIVATE_PYPI_SIMPLE_URL` only when the simple URL ends in `/simple/` or `/simple`.

No private IP, domain, or fallback registry URL is hardcoded in this repository.

Swift generation also supports numeric `exclusiveMinimum`/`exclusiveMaximum`, closed-object `oneOf` branches proven disjoint by required property names, and nullable schema references. Pattern validation uses Foundation regular expressions for a conservative ASCII syntax subset (including `\s`/`\S`); advanced groups, other escapes and non-ASCII patterns fail generation. Decoding and encoding both apply supported constraints.
