codapact 0.2.0__tar.gz → 0.4.0__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.
- codapact-0.4.0/.github/workflows/ci.yml +148 -0
- codapact-0.4.0/.github/workflows/mutation.yml +67 -0
- codapact-0.4.0/.github/workflows/nightly.yml +50 -0
- codapact-0.4.0/.release-please-manifest.json +1 -0
- {codapact-0.2.0 → codapact-0.4.0}/CHANGELOG.md +26 -0
- codapact-0.4.0/PKG-INFO +87 -0
- codapact-0.4.0/README.md +72 -0
- codapact-0.4.0/docs/architecture.md +155 -0
- codapact-0.2.0/docs/branding.md → codapact-0.4.0/docs/branding/README.md +11 -2
- codapact-0.4.0/docs/configuration.md +276 -0
- codapact-0.4.0/docs/testing.md +90 -0
- codapact-0.4.0/examples/library/codapact.yaml +20 -0
- codapact-0.4.0/examples/library/operations.graphql +13 -0
- codapact-0.4.0/examples/library/schema.graphql +49 -0
- codapact-0.4.0/examples/petstore/codapact.yaml +23 -0
- codapact-0.4.0/examples/petstore/openapi.yaml +131 -0
- {codapact-0.2.0 → codapact-0.4.0}/pyproject.toml +76 -23
- codapact-0.4.0/pyproject.toml.orig +122 -0
- codapact-0.4.0/scripts/extract_openapi_subset.py +93 -0
- codapact-0.4.0/scripts/mutation_score.py +86 -0
- codapact-0.4.0/src/codapact/__init__.py +8 -0
- codapact-0.4.0/src/codapact/__main__.py +5 -0
- codapact-0.4.0/src/codapact/commands/__init__.py +1 -0
- codapact-0.4.0/src/codapact/commands/derive.py +206 -0
- codapact-0.4.0/src/codapact/commands/model.py +88 -0
- codapact-0.4.0/src/codapact/core/__init__.py +5 -0
- codapact-0.4.0/src/codapact/core/diagnostics.py +109 -0
- codapact-0.4.0/src/codapact/core/errors.py +48 -0
- codapact-0.4.0/src/codapact/core/naming.py +73 -0
- codapact-0.4.0/src/codapact/core/net.py +254 -0
- codapact-0.4.0/src/codapact/model/__init__.py +92 -0
- codapact-0.4.0/src/codapact/model/api.py +288 -0
- codapact-0.4.0/src/codapact/model/authspec.py +98 -0
- codapact-0.4.0/src/codapact/model/migrations.py +58 -0
- codapact-0.4.0/src/codapact/model/rewrite.py +95 -0
- codapact-0.4.0/src/codapact/model/serialize.py +208 -0
- codapact-0.4.0/src/codapact/model/types.py +196 -0
- codapact-0.4.0/src/codapact/model/validate.py +140 -0
- codapact-0.4.0/src/codapact/model/values.py +5 -0
- codapact-0.4.0/src/codapact/pipeline/__init__.py +1 -0
- codapact-0.4.0/src/codapact/pipeline/cli.py +136 -0
- codapact-0.4.0/src/codapact/pipeline/config.py +151 -0
- codapact-0.4.0/src/codapact/pipeline/defaults.py +31 -0
- codapact-0.4.0/src/codapact/pipeline/pipeline.py +180 -0
- codapact-0.4.0/src/codapact/pipeline/writer.py +133 -0
- codapact-0.4.0/src/codapact/plugins/__init__.py +1 -0
- codapact-0.4.0/src/codapact/plugins/external.py +77 -0
- codapact-0.4.0/src/codapact/plugins/protocol.py +198 -0
- codapact-0.4.0/src/codapact/plugins/registry.py +61 -0
- codapact-0.4.0/src/codapact/runtime/__init__.py +74 -0
- codapact-0.4.0/src/codapact/runtime/abstractions.py +112 -0
- codapact-0.4.0/src/codapact/runtime/arguments.py +50 -0
- codapact-0.4.0/src/codapact/runtime/auth.py +256 -0
- codapact-0.4.0/src/codapact/runtime/cli.py +1321 -0
- codapact-0.4.0/src/codapact/runtime/cli_auth.py +241 -0
- codapact-0.4.0/src/codapact/runtime/cli_tools.py +563 -0
- codapact-0.4.0/src/codapact/runtime/client.py +175 -0
- codapact-0.4.0/src/codapact/runtime/codec.py +279 -0
- codapact-0.4.0/src/codapact/runtime/credentials.py +331 -0
- codapact-0.4.0/src/codapact/runtime/errors.py +84 -0
- codapact-0.4.0/src/codapact/runtime/middleware.py +66 -0
- codapact-0.4.0/src/codapact/runtime/oauth.py +849 -0
- codapact-0.4.0/src/codapact/runtime/protocols/__init__.py +1 -0
- codapact-0.4.0/src/codapact/runtime/protocols/base.py +113 -0
- codapact-0.4.0/src/codapact/runtime/protocols/graphql.py +65 -0
- codapact-0.4.0/src/codapact/runtime/protocols/http.py +155 -0
- codapact-0.4.0/src/codapact/runtime/selftest.py +339 -0
- codapact-0.4.0/src/codapact/shaping/__init__.py +1 -0
- codapact-0.4.0/src/codapact/shaping/base.py +36 -0
- codapact-0.4.0/src/codapact/shaping/engine.py +60 -0
- codapact-0.4.0/src/codapact/shaping/transforms.py +521 -0
- codapact-0.4.0/src/codapact/sources/__init__.py +1 -0
- codapact-0.4.0/src/codapact/sources/base.py +53 -0
- codapact-0.4.0/src/codapact/sources/graphql/__init__.py +5 -0
- codapact-0.4.0/src/codapact/sources/graphql/translator.py +648 -0
- codapact-0.4.0/src/codapact/sources/loader.py +151 -0
- codapact-0.4.0/src/codapact/sources/openapi/__init__.py +5 -0
- codapact-0.4.0/src/codapact/sources/openapi/translator.py +874 -0
- codapact-0.4.0/src/codapact/surface/__init__.py +1 -0
- codapact-0.4.0/src/codapact/surface/derive.py +293 -0
- codapact-0.4.0/src/codapact/surface/model.py +109 -0
- codapact-0.4.0/src/codapact/targets/__init__.py +1 -0
- codapact-0.4.0/src/codapact/targets/python/__init__.py +1 -0
- codapact-0.4.0/src/codapact/targets/python/cli.py +423 -0
- codapact-0.4.0/src/codapact/targets/python/e2e.py +373 -0
- codapact-0.4.0/src/codapact/targets/python/library.py +381 -0
- codapact-0.4.0/src/codapact/targets/python/naming.py +106 -0
- codapact-0.4.0/src/codapact/targets/typescript/__init__.py +1 -0
- codapact-0.4.0/src/codapact/targets/typescript/library.py +430 -0
- codapact-0.4.0/src/codapact/targets/typescript/runtime.ts +449 -0
- codapact-0.4.0/tests/authlab.py +288 -0
- codapact-0.4.0/tests/conftest.py +53 -0
- codapact-0.4.0/tests/e2e/test_auth_e2e.py +308 -0
- codapact-0.4.0/tests/e2e/test_cli_e2e.py +251 -0
- codapact-0.4.0/tests/e2e/test_public_apis.py +214 -0
- codapact-0.4.0/tests/fixtures/authlab/authlab_plugin.py +41 -0
- codapact-0.4.0/tests/fixtures/authlab/codapact.yaml +21 -0
- codapact-0.4.0/tests/fixtures/authlab/fake_browser.py +26 -0
- codapact-0.4.0/tests/fixtures/authlab/openapi.yaml +82 -0
- codapact-0.4.0/tests/fixtures/authlab_smoke.ts +63 -0
- codapact-0.4.0/tests/fixtures/contracts/wire.yaml +50 -0
- codapact-0.4.0/tests/fixtures/corpus/README.md +15 -0
- codapact-0.4.0/tests/fixtures/corpus/countries/codapact.yaml +12 -0
- codapact-0.4.0/tests/fixtures/corpus/countries/operations.graphql +15 -0
- codapact-0.4.0/tests/fixtures/corpus/countries/schema.graphql +24 -0
- codapact-0.4.0/tests/fixtures/corpus/github/codapact.yaml +41 -0
- codapact-0.4.0/tests/fixtures/corpus/github/openapi.json +4724 -0
- codapact-0.4.0/tests/fixtures/corpus/pokeapi/codapact.yaml +66 -0
- codapact-0.4.0/tests/fixtures/corpus/pokeapi/openapi.yml +10450 -0
- codapact-0.4.0/tests/fixtures/corpus/ynab/README.md +6 -0
- codapact-0.4.0/tests/fixtures/corpus/ynab/codapact.yaml +13 -0
- codapact-0.4.0/tests/fixtures/corpus/ynab/openapi.yaml +4027 -0
- codapact-0.4.0/tests/fixtures/library_smoke.ts +11 -0
- codapact-0.4.0/tests/fixtures/outline_plugin.py +43 -0
- codapact-0.4.0/tests/fixtures/petstore_smoke.ts +15 -0
- codapact-0.4.0/tests/fixtures/wire_parity.ts +17 -0
- codapact-0.4.0/tests/integration/test_cli_conformance.py +268 -0
- codapact-0.4.0/tests/integration/test_cli_conventions.py +188 -0
- codapact-0.4.0/tests/integration/test_contract_properties.py +123 -0
- codapact-0.4.0/tests/integration/test_corpus.py +118 -0
- codapact-0.4.0/tests/integration/test_generated_code_properties.py +85 -0
- codapact-0.4.0/tests/integration/test_generation.py +235 -0
- codapact-0.4.0/tests/integration/test_public_api_cli.py +106 -0
- codapact-0.4.0/tests/integration/test_wire_parity.py +104 -0
- codapact-0.4.0/tests/integration/test_ynab_contract.py +275 -0
- codapact-0.4.0/tests/perf/test_scaling.py +166 -0
- codapact-0.4.0/tests/public_api_contract.py +122 -0
- codapact-0.4.0/tests/strategies.py +204 -0
- codapact-0.4.0/tests/support.py +409 -0
- codapact-0.4.0/tests/unit/test_architecture.py +91 -0
- codapact-0.4.0/tests/unit/test_auth_and_graphql_sources.py +126 -0
- codapact-0.4.0/tests/unit/test_auth_sources.py +529 -0
- codapact-0.4.0/tests/unit/test_bundle_e2e.py +474 -0
- codapact-0.4.0/tests/unit/test_cli_builtins.py +532 -0
- codapact-0.4.0/tests/unit/test_codec_serialize.py +155 -0
- codapact-0.4.0/tests/unit/test_core.py +77 -0
- codapact-0.4.0/tests/unit/test_guards.py +233 -0
- codapact-0.4.0/tests/unit/test_model.py +179 -0
- codapact-0.4.0/tests/unit/test_mutation_score.py +60 -0
- codapact-0.4.0/tests/unit/test_oauth.py +590 -0
- codapact-0.4.0/tests/unit/test_openapi_edges.py +341 -0
- codapact-0.4.0/tests/unit/test_openapi_translator_units.py +388 -0
- codapact-0.4.0/tests/unit/test_plugins_pipeline.py +245 -0
- codapact-0.4.0/tests/unit/test_public_api_findings.py +932 -0
- codapact-0.4.0/tests/unit/test_runtime.py +302 -0
- codapact-0.4.0/tests/unit/test_runtime_edges.py +202 -0
- codapact-0.4.0/tests/unit/test_runtime_pagination.py +116 -0
- codapact-0.4.0/tests/unit/test_shaping_surface_commands.py +227 -0
- codapact-0.4.0/tests/unit/test_sources.py +357 -0
- codapact-0.4.0/tests/unit/test_target_rendering.py +332 -0
- codapact-0.4.0/tests/unit/test_usability.py +291 -0
- {codapact-0.2.0 → codapact-0.4.0}/uv.lock +198 -12
- codapact-0.2.0/.github/workflows/ci.yml +0 -53
- codapact-0.2.0/.github/workflows/mutation-alerts.yml +0 -73
- codapact-0.2.0/.github/workflows/mutation.yml +0 -55
- codapact-0.2.0/.release-please-manifest.json +0 -1
- codapact-0.2.0/PKG-INFO +0 -74
- codapact-0.2.0/README.md +0 -59
- codapact-0.2.0/docs/architecture.md +0 -84
- codapact-0.2.0/docs/configuration.md +0 -175
- codapact-0.2.0/docs/mutation-review-ab121cb.json +0 -427
- codapact-0.2.0/docs/mutation.md +0 -106
- codapact-0.2.0/docs/releasing.md +0 -41
- codapact-0.2.0/docs/security.md +0 -35
- codapact-0.2.0/docs/selection.md +0 -176
- codapact-0.2.0/docs/support.md +0 -92
- codapact-0.2.0/docs/verification.md +0 -69
- codapact-0.2.0/examples/cli.json +0 -4
- codapact-0.2.0/examples/domains.openapi.yaml +0 -109
- codapact-0.2.0/examples/pets-read.cli.yaml +0 -6
- codapact-0.2.0/examples/pets-read.codapact.yaml +0 -19
- codapact-0.2.0/examples/pets.codapact.yaml +0 -18
- codapact-0.2.0/examples/pets.yaml +0 -43
- codapact-0.2.0/examples/runtime.json +0 -5
- codapact-0.2.0/pyproject.toml.orig +0 -75
- codapact-0.2.0/schemas/cli.v1.schema.json +0 -23
- codapact-0.2.0/scripts/mutation_alerts.py +0 -418
- codapact-0.2.0/scripts/mutation_report.py +0 -110
- codapact-0.2.0/src/codapact/__init__.py +0 -3
- codapact-0.2.0/src/codapact/__main__.py +0 -107
- codapact-0.2.0/src/codapact/auth.py +0 -68
- codapact-0.2.0/src/codapact/cli.py +0 -117
- codapact-0.2.0/src/codapact/configuration.py +0 -138
- codapact-0.2.0/src/codapact/errors.py +0 -30
- codapact-0.2.0/src/codapact/generation.py +0 -259
- codapact-0.2.0/src/codapact/loading.py +0 -135
- codapact-0.2.0/src/codapact/model.py +0 -119
- codapact-0.2.0/src/codapact/net.py +0 -106
- codapact-0.2.0/src/codapact/openapi.py +0 -304
- codapact-0.2.0/src/codapact/profiles.py +0 -175
- codapact-0.2.0/src/codapact/project.py +0 -209
- codapact-0.2.0/src/codapact/runtime.py +0 -197
- codapact-0.2.0/src/codapact/schemas/generation.v1.json +0 -227
- codapact-0.2.0/src/codapact/selection.py +0 -198
- codapact-0.2.0/src/codapact/validation.py +0 -67
- codapact-0.2.0/src/codapact/values.py +0 -33
- codapact-0.2.0/tests/__init__.py +0 -1
- codapact-0.2.0/tests/assertions.py +0 -15
- codapact-0.2.0/tests/conftest.py +0 -206
- codapact-0.2.0/tests/test_adversarial.py +0 -141
- codapact-0.2.0/tests/test_configuration.py +0 -441
- codapact-0.2.0/tests/test_distribution.py +0 -111
- codapact-0.2.0/tests/test_entrypoint.py +0 -75
- codapact-0.2.0/tests/test_generated_contracts.py +0 -746
- codapact-0.2.0/tests/test_generation.py +0 -269
- codapact-0.2.0/tests/test_loading.py +0 -244
- codapact-0.2.0/tests/test_mutation_alerts.py +0 -363
- codapact-0.2.0/tests/test_mutation_contracts.py +0 -1281
- codapact-0.2.0/tests/test_net.py +0 -272
- codapact-0.2.0/tests/test_openapi.py +0 -85
- codapact-0.2.0/tests/test_reference_text_budget.py +0 -34
- codapact-0.2.0/tests/test_residual_contracts.py +0 -137
- codapact-0.2.0/tests/test_runtime.py +0 -231
- codapact-0.2.0/tests/test_selection.py +0 -248
- codapact-0.2.0/tests/test_selection_generation.py +0 -377
- {codapact-0.2.0 → codapact-0.4.0}/.github/workflows/codeql.yml +0 -0
- {codapact-0.2.0 → codapact-0.4.0}/.github/workflows/release.yml +0 -0
- {codapact-0.2.0 → codapact-0.4.0}/LICENSE +0 -0
- {codapact-0.2.0 → codapact-0.4.0/docs}/branding/mark.svg +0 -0
- {codapact-0.2.0 → codapact-0.4.0/docs}/branding/wordmark.svg +0 -0
- {codapact-0.2.0 → codapact-0.4.0}/release-please-config.json +0 -0
- {codapact-0.2.0 → codapact-0.4.0}/scripts/verify_dist.py +0 -0
- {codapact-0.2.0 → codapact-0.4.0}/src/codapact/py.typed +0 -0
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
on:
|
|
3
|
+
pull_request:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
workflow_call:
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
jobs:
|
|
11
|
+
title:
|
|
12
|
+
name: Conventional PR title
|
|
13
|
+
if: github.event_name == 'pull_request'
|
|
14
|
+
runs-on: ubuntu-latest
|
|
15
|
+
steps:
|
|
16
|
+
- name: Check title
|
|
17
|
+
env:
|
|
18
|
+
TITLE: ${{ github.event.pull_request.title }}
|
|
19
|
+
run: |
|
|
20
|
+
pattern='^(feat|fix|perf|docs|build|ci|refactor|test|chore|style|revert)(\([^)]+\))?!?: .+'
|
|
21
|
+
[[ "$TITLE" =~ $pattern ]]
|
|
22
|
+
check:
|
|
23
|
+
name: Python ${{ matrix.python }} on ${{ matrix.os }}
|
|
24
|
+
runs-on: ${{ matrix.os }}
|
|
25
|
+
strategy:
|
|
26
|
+
fail-fast: false
|
|
27
|
+
matrix:
|
|
28
|
+
os: [ubuntu-latest, windows-latest]
|
|
29
|
+
python: ['3.13', '3.14']
|
|
30
|
+
env:
|
|
31
|
+
# TypeScript runtime tests must run, not skip, in CI.
|
|
32
|
+
CODAPACT_REQUIRE_NODE: '1'
|
|
33
|
+
steps:
|
|
34
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
35
|
+
with:
|
|
36
|
+
persist-credentials: false
|
|
37
|
+
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
38
|
+
with:
|
|
39
|
+
python-version: ${{ matrix.python }}
|
|
40
|
+
enable-cache: false
|
|
41
|
+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
42
|
+
with:
|
|
43
|
+
node-version: '24'
|
|
44
|
+
- name: Install TypeScript compiler
|
|
45
|
+
shell: bash
|
|
46
|
+
run: |
|
|
47
|
+
npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" typescript@6.0.2
|
|
48
|
+
echo "$RUNNER_TEMP/tools/node_modules/.bin" >> "$GITHUB_PATH"
|
|
49
|
+
- run: uv sync --locked
|
|
50
|
+
- run: uv run poe check
|
|
51
|
+
- run: uv build
|
|
52
|
+
- run: uv run twine check --strict dist/*
|
|
53
|
+
|
|
54
|
+
coverage:
|
|
55
|
+
name: Coverage of changed lines
|
|
56
|
+
if: github.event_name == 'pull_request'
|
|
57
|
+
runs-on: ubuntu-latest
|
|
58
|
+
env:
|
|
59
|
+
CODAPACT_REQUIRE_NODE: '1'
|
|
60
|
+
HYPOTHESIS_PROFILE: ci
|
|
61
|
+
steps:
|
|
62
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
63
|
+
with:
|
|
64
|
+
persist-credentials: false
|
|
65
|
+
fetch-depth: 0
|
|
66
|
+
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
67
|
+
with:
|
|
68
|
+
python-version: '3.13'
|
|
69
|
+
enable-cache: false
|
|
70
|
+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
71
|
+
with:
|
|
72
|
+
node-version: '24'
|
|
73
|
+
- run: |
|
|
74
|
+
npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" typescript@6.0.2
|
|
75
|
+
echo "$RUNNER_TEMP/tools/node_modules/.bin" >> "$GITHUB_PATH"
|
|
76
|
+
- run: uv sync --locked
|
|
77
|
+
- name: Full suite with more property examples
|
|
78
|
+
run: uv run poe test
|
|
79
|
+
- name: Every changed source line is covered
|
|
80
|
+
env:
|
|
81
|
+
BASE_REF: ${{ github.base_ref }}
|
|
82
|
+
run: |
|
|
83
|
+
git fetch --no-tags origin "$BASE_REF"
|
|
84
|
+
uv run diff-cover coverage.xml --compare-branch="origin/$BASE_REF" --fail-under=100 \
|
|
85
|
+
--markdown-report diff-coverage.md
|
|
86
|
+
cat diff-coverage.md >> "$GITHUB_STEP_SUMMARY"
|
|
87
|
+
|
|
88
|
+
prism:
|
|
89
|
+
name: E2E against Prism mock (PokeAPI)
|
|
90
|
+
runs-on: ubuntu-latest
|
|
91
|
+
steps:
|
|
92
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
93
|
+
with:
|
|
94
|
+
persist-credentials: false
|
|
95
|
+
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
96
|
+
with:
|
|
97
|
+
python-version: '3.13'
|
|
98
|
+
enable-cache: false
|
|
99
|
+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
100
|
+
with:
|
|
101
|
+
node-version: '24'
|
|
102
|
+
- run: npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" @stoplight/prism-cli@5.16.0
|
|
103
|
+
- run: uv sync --locked
|
|
104
|
+
- name: Start Prism (validates every request against the pinned spec)
|
|
105
|
+
run: |
|
|
106
|
+
"$RUNNER_TEMP/tools/node_modules/.bin/prism" mock --errors -p 4010 \
|
|
107
|
+
tests/fixtures/corpus/pokeapi/openapi.yml > "$RUNNER_TEMP/prism.log" 2>&1 &
|
|
108
|
+
for _ in $(seq 60); do curl -s -o /dev/null http://127.0.0.1:4010/ && break; sleep 1; done
|
|
109
|
+
- run: uv run pytest tests/e2e/test_public_apis.py -v
|
|
110
|
+
env:
|
|
111
|
+
CODAPACT_PRISM_URL: http://127.0.0.1:4010
|
|
112
|
+
- if: always()
|
|
113
|
+
run: cat "$RUNNER_TEMP/prism.log"
|
|
114
|
+
|
|
115
|
+
perf:
|
|
116
|
+
name: Performance budgets
|
|
117
|
+
runs-on: ubuntu-latest
|
|
118
|
+
steps:
|
|
119
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
120
|
+
with:
|
|
121
|
+
persist-credentials: false
|
|
122
|
+
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
123
|
+
with:
|
|
124
|
+
python-version: '3.13'
|
|
125
|
+
enable-cache: false
|
|
126
|
+
- run: uv sync --locked
|
|
127
|
+
- run: uv run poe test-perf
|
|
128
|
+
env:
|
|
129
|
+
CODAPACT_PERF_REPORT: perf-report.json
|
|
130
|
+
- if: always()
|
|
131
|
+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
132
|
+
with:
|
|
133
|
+
name: perf-report
|
|
134
|
+
path: perf-report.json
|
|
135
|
+
if-no-files-found: warn
|
|
136
|
+
retention-days: 30
|
|
137
|
+
|
|
138
|
+
passed:
|
|
139
|
+
name: CI passed
|
|
140
|
+
if: always()
|
|
141
|
+
needs: [check, coverage, prism, perf, title]
|
|
142
|
+
runs-on: ubuntu-latest
|
|
143
|
+
steps:
|
|
144
|
+
- name: Require all checks
|
|
145
|
+
env:
|
|
146
|
+
RESULTS: ${{ toJSON(needs) }}
|
|
147
|
+
run: |
|
|
148
|
+
echo "$RESULTS" | jq -e 'to_entries | all(.value.result == "success" or .value.result == "skipped")'
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
name: Mutation
|
|
2
|
+
# Mutation testing measures whether the tests notice behavior changes. It is slow
|
|
3
|
+
# (~9k mutants), so it runs in parallel shards after merges to main, weekly, and on
|
|
4
|
+
# demand; it never gates a PR. Each shard must finish and meet the score floor.
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
branches: [main]
|
|
8
|
+
schedule:
|
|
9
|
+
- cron: '23 6 * * 1'
|
|
10
|
+
workflow_dispatch:
|
|
11
|
+
permissions:
|
|
12
|
+
contents: read
|
|
13
|
+
concurrency:
|
|
14
|
+
group: mutation-${{ github.ref }}
|
|
15
|
+
cancel-in-progress: true
|
|
16
|
+
jobs:
|
|
17
|
+
mutmut:
|
|
18
|
+
name: mutmut ${{ matrix.shard.name }}
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
timeout-minutes: 75
|
|
21
|
+
strategy:
|
|
22
|
+
fail-fast: false
|
|
23
|
+
matrix:
|
|
24
|
+
shard:
|
|
25
|
+
- {name: openapi, patterns: 'codapact.sources.openapi.*'}
|
|
26
|
+
- {name: sources, patterns: 'codapact.sources.graphql.* codapact.sources.loader.* codapact.sources.base.*'}
|
|
27
|
+
- {name: targets, patterns: 'codapact.targets.*'}
|
|
28
|
+
- {name: runtime, patterns: 'codapact.runtime.*'}
|
|
29
|
+
- {name: pipeline, patterns: 'codapact.pipeline.* codapact.plugins.* codapact.commands.*'}
|
|
30
|
+
- {name: model, patterns: 'codapact.model.* codapact.shaping.* codapact.surface.* codapact.core.*'}
|
|
31
|
+
env:
|
|
32
|
+
# Baseline 2026-11-11: ~74% overall. Raise as survivors are fixed; never lower.
|
|
33
|
+
MUTATION_FLOOR: '70'
|
|
34
|
+
steps:
|
|
35
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
36
|
+
with:
|
|
37
|
+
persist-credentials: false
|
|
38
|
+
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
39
|
+
with:
|
|
40
|
+
python-version: '3.13'
|
|
41
|
+
enable-cache: false
|
|
42
|
+
- run: uv sync --locked --group mutation
|
|
43
|
+
- name: Run mutmut
|
|
44
|
+
env:
|
|
45
|
+
PATTERNS: ${{ matrix.shard.patterns }}
|
|
46
|
+
run: |
|
|
47
|
+
set +e
|
|
48
|
+
read -ra patterns <<< "$PATTERNS"
|
|
49
|
+
timeout --signal=TERM --kill-after=30s 65m uv run mutmut run --max-children 4 "${patterns[@]}"
|
|
50
|
+
echo "run_exit=$?" >> "$GITHUB_ENV"
|
|
51
|
+
mkdir -p mutation-report
|
|
52
|
+
uv run mutmut results --all true > mutation-report/results.txt
|
|
53
|
+
- name: Enforce mutation score floor
|
|
54
|
+
env:
|
|
55
|
+
PATTERNS: ${{ matrix.shard.patterns }}
|
|
56
|
+
run: |
|
|
57
|
+
test "$run_exit" = 0 || { echo "mutmut did not finish (exit $run_exit)"; exit 1; }
|
|
58
|
+
args=()
|
|
59
|
+
for pattern in $PATTERNS; do args+=(--prefix "${pattern%\*}"); done
|
|
60
|
+
uv run python scripts/mutation_score.py --results mutation-report/results.txt "${args[@]}"
|
|
61
|
+
- if: always()
|
|
62
|
+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
63
|
+
with:
|
|
64
|
+
name: mutation-report-${{ matrix.shard.name }}
|
|
65
|
+
path: mutation-report/
|
|
66
|
+
if-no-files-found: warn
|
|
67
|
+
retention-days: 30
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
name: Nightly
|
|
2
|
+
# Slow and networked suites that should not gate every PR:
|
|
3
|
+
# live public APIs, deep property-based fuzzing, and the full TypeScript fuzz.
|
|
4
|
+
on:
|
|
5
|
+
schedule:
|
|
6
|
+
- cron: '17 5 * * *'
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
jobs:
|
|
11
|
+
live:
|
|
12
|
+
name: Live public APIs (PokeAPI, Countries, GitHub with auth)
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
timeout-minutes: 20
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
17
|
+
with:
|
|
18
|
+
persist-credentials: false
|
|
19
|
+
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
20
|
+
with:
|
|
21
|
+
python-version: '3.13'
|
|
22
|
+
enable-cache: false
|
|
23
|
+
- run: uv sync --locked
|
|
24
|
+
- run: uv run poe test-live -v
|
|
25
|
+
env:
|
|
26
|
+
# The generated GitHub CLI's live e2e suite proves the token is sent
|
|
27
|
+
# (authenticated rate limit) and that GitHub rejects a bad one.
|
|
28
|
+
GHX_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
29
|
+
deep:
|
|
30
|
+
name: Deep property-based fuzzing
|
|
31
|
+
runs-on: ubuntu-latest
|
|
32
|
+
timeout-minutes: 60
|
|
33
|
+
env:
|
|
34
|
+
CODAPACT_REQUIRE_NODE: '1'
|
|
35
|
+
steps:
|
|
36
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
37
|
+
with:
|
|
38
|
+
persist-credentials: false
|
|
39
|
+
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
40
|
+
with:
|
|
41
|
+
python-version: '3.13'
|
|
42
|
+
enable-cache: false
|
|
43
|
+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
44
|
+
with:
|
|
45
|
+
node-version: '24'
|
|
46
|
+
- run: |
|
|
47
|
+
npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" typescript@6.0.2
|
|
48
|
+
echo "$RUNNER_TEMP/tools/node_modules/.bin" >> "$GITHUB_PATH"
|
|
49
|
+
- run: uv sync --locked
|
|
50
|
+
- run: uv run poe test-deep
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{".":"0.4.0"}
|
|
@@ -2,6 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- markdownlint-configure-file { "MD024": { "siblings_only": true } } -->
|
|
4
4
|
|
|
5
|
+
## [0.4.0](https://github.com/mikejhill/codapact/compare/v0.3.0...v0.4.0) (2026-11-12)
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
### Features
|
|
9
|
+
|
|
10
|
+
* **auth:** pluggable auth (OAuth 2.0 flows, bespoke authenticators) and generated bundle e2e suites ([#27](https://github.com/mikejhill/codapact/issues/27)) ([b42cb61](https://github.com/mikejhill/codapact/commit/b42cb61165c58895893c1a50a5515d5dc39a88aa))
|
|
11
|
+
* **cli:** conventional help, version, describe, doctor, completion, dry-run, JSON errors ([#25](https://github.com/mikejhill/codapact/issues/25)) ([809c9da](https://github.com/mikejhill/codapact/commit/809c9da83102ebaa5ae41a0cd0d60177e10c286f))
|
|
12
|
+
* **cli:** name commands in errors, describe --brief and schemas, CLI conformance suite ([#26](https://github.com/mikejhill/codapact/issues/26)) ([8780dfc](https://github.com/mikejhill/codapact/commit/8780dfcf1607f267cf59c9d39e8dd4c61a895da7))
|
|
13
|
+
* fix YNAB-evaluation findings (nullability, allOf, naming, CLI usability) ([#22](https://github.com/mikejhill/codapact/issues/22)) ([d8caaf3](https://github.com/mikejhill/codapact/commit/d8caaf33d084770993a5ad45d7bfb3d01d5d7cf9))
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
### Bug Fixes
|
|
17
|
+
|
|
18
|
+
* address defects found by generating clients for PokeAPI and GitHub ([#23](https://github.com/mikejhill/codapact/issues/23)) ([b0693c3](https://github.com/mikejhill/codapact/commit/b0693c370d0fbfc6483cdc82adc4015c375a05a1))
|
|
19
|
+
|
|
20
|
+
## [0.3.0](https://github.com/mikejhill/codapact/compare/v0.2.0...v0.3.0) (2026-11-10)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
### ⚠ BREAKING CHANGES
|
|
24
|
+
|
|
25
|
+
* the CLI, configuration format, and generated code are new.
|
|
26
|
+
|
|
27
|
+
### Features
|
|
28
|
+
|
|
29
|
+
* rewrite codapact as a layered contract-to-library-and-CLI generator ([#20](https://github.com/mikejhill/codapact/issues/20)) ([594ae46](https://github.com/mikejhill/codapact/commit/594ae46258b64d478e33313c9ca93033cbfff226))
|
|
30
|
+
|
|
5
31
|
## [0.2.0](https://github.com/mikejhill/codapact/compare/v0.1.1...v0.2.0) (2026-10-29)
|
|
6
32
|
|
|
7
33
|
### Features
|
codapact-0.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codapact
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Contracts into callable tools: generate libraries, then CLIs, from OpenAPI, GraphQL, and other API contracts.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Dist: pyyaml>=6.0.3,<7
|
|
8
|
+
Requires-Dist: graphql-core>=3.2.6,<4
|
|
9
|
+
Requires-Python: >=3.13
|
|
10
|
+
Project-URL: Homepage, https://github.com/mikejhill/codapact
|
|
11
|
+
Project-URL: Documentation, https://github.com/mikejhill/codapact#readme
|
|
12
|
+
Project-URL: Changelog, https://github.com/mikejhill/codapact/blob/main/CHANGELOG.md
|
|
13
|
+
Project-URL: Issues, https://github.com/mikejhill/codapact/issues
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
type: overview
|
|
18
|
+
status: active
|
|
19
|
+
authority: informative
|
|
20
|
+
criticality: low
|
|
21
|
+
review:
|
|
22
|
+
status: unreviewed
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
# CodaPact
|
|
26
|
+
|
|
27
|
+

|
|
28
|
+
|
|
29
|
+
**Contracts into callable tools.** Read an API contract (OpenAPI 3.0/3.1 or GraphQL),
|
|
30
|
+
generate a typed library, then generate a CLI on top of that library.
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
contract ──► sources ──► semantic model ──► shaping ──► library surface ──► command model
|
|
34
|
+
(OpenAPI, (L1) (L2) (L3) (L4) (L5)
|
|
35
|
+
GraphQL) │ │
|
|
36
|
+
▼ ▼
|
|
37
|
+
library targets CLI targets
|
|
38
|
+
(Python, TS, plugin) (Python CLI)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Try it
|
|
42
|
+
|
|
43
|
+
Prerequisites: Git and [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
44
|
+
|
|
45
|
+
```console
|
|
46
|
+
git clone https://github.com/mikejhill/codapact.git
|
|
47
|
+
cd codapact
|
|
48
|
+
uv sync --locked
|
|
49
|
+
uv run codapact generate -c examples/petstore/codapact.yaml
|
|
50
|
+
uv run --with . --with ./examples/petstore/generated/python petstore pets list --help
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Quick mode, no project file:
|
|
54
|
+
|
|
55
|
+
```console
|
|
56
|
+
uv run codapact generate --source openapi.yaml --target python --target python-cli \
|
|
57
|
+
--package acme --program acme --out out/
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Inspect any intermediate layer as JSON:
|
|
61
|
+
|
|
62
|
+
```console
|
|
63
|
+
uv run codapact inspect model -c examples/library/codapact.yaml
|
|
64
|
+
uv run codapact inspect surface -c examples/library/codapact.yaml
|
|
65
|
+
uv run codapact inspect commands -c examples/library/codapact.yaml
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## What you get
|
|
69
|
+
|
|
70
|
+
| Output | Contents |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `python` | Installable package: `TypedDict` types, a resource-per-namespace client, paging iterators, `py.typed` |
|
|
73
|
+
| `python-cli` | argparse CLI calling the Python library: `--help` with examples, `--version`, `describe` (JSON catalog for agents), `doctor`, shell `completion`, `--dry-run`, JSON/JSONL/YAML/table output, JSON errors, documented exit codes; env + XDG settings |
|
|
74
|
+
| `typescript` | Fetch-based client with bundled runtime; strict `tsc` clean |
|
|
75
|
+
| external plugin | Any executable speaking the JSON plugin protocol |
|
|
76
|
+
|
|
77
|
+
Generated code is a thin facade over `codapact.runtime`: retries, auth, validation, and
|
|
78
|
+
pagination live in one tested place and improve without regenerating.
|
|
79
|
+
|
|
80
|
+
## Documents
|
|
81
|
+
|
|
82
|
+
- [Architecture](docs/architecture.md): layers, dependency rules, extension seams, and
|
|
83
|
+
lessons taken from Smithy, Fern, Kiota, protoc, Stainless, Speakeasy, graphql-codegen,
|
|
84
|
+
and restish.
|
|
85
|
+
- [Configuration](docs/configuration.md): `codapact.yaml`, shaping transforms, target
|
|
86
|
+
options, and generated CLI settings.
|
|
87
|
+
- [Contributing](CONTRIBUTING.md)
|
codapact-0.4.0/README.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: overview
|
|
3
|
+
status: active
|
|
4
|
+
authority: informative
|
|
5
|
+
criticality: low
|
|
6
|
+
review:
|
|
7
|
+
status: unreviewed
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# CodaPact
|
|
11
|
+
|
|
12
|
+

|
|
13
|
+
|
|
14
|
+
**Contracts into callable tools.** Read an API contract (OpenAPI 3.0/3.1 or GraphQL),
|
|
15
|
+
generate a typed library, then generate a CLI on top of that library.
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
contract ──► sources ──► semantic model ──► shaping ──► library surface ──► command model
|
|
19
|
+
(OpenAPI, (L1) (L2) (L3) (L4) (L5)
|
|
20
|
+
GraphQL) │ │
|
|
21
|
+
▼ ▼
|
|
22
|
+
library targets CLI targets
|
|
23
|
+
(Python, TS, plugin) (Python CLI)
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Try it
|
|
27
|
+
|
|
28
|
+
Prerequisites: Git and [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
29
|
+
|
|
30
|
+
```console
|
|
31
|
+
git clone https://github.com/mikejhill/codapact.git
|
|
32
|
+
cd codapact
|
|
33
|
+
uv sync --locked
|
|
34
|
+
uv run codapact generate -c examples/petstore/codapact.yaml
|
|
35
|
+
uv run --with . --with ./examples/petstore/generated/python petstore pets list --help
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Quick mode, no project file:
|
|
39
|
+
|
|
40
|
+
```console
|
|
41
|
+
uv run codapact generate --source openapi.yaml --target python --target python-cli \
|
|
42
|
+
--package acme --program acme --out out/
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Inspect any intermediate layer as JSON:
|
|
46
|
+
|
|
47
|
+
```console
|
|
48
|
+
uv run codapact inspect model -c examples/library/codapact.yaml
|
|
49
|
+
uv run codapact inspect surface -c examples/library/codapact.yaml
|
|
50
|
+
uv run codapact inspect commands -c examples/library/codapact.yaml
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## What you get
|
|
54
|
+
|
|
55
|
+
| Output | Contents |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| `python` | Installable package: `TypedDict` types, a resource-per-namespace client, paging iterators, `py.typed` |
|
|
58
|
+
| `python-cli` | argparse CLI calling the Python library: `--help` with examples, `--version`, `describe` (JSON catalog for agents), `doctor`, shell `completion`, `--dry-run`, JSON/JSONL/YAML/table output, JSON errors, documented exit codes; env + XDG settings |
|
|
59
|
+
| `typescript` | Fetch-based client with bundled runtime; strict `tsc` clean |
|
|
60
|
+
| external plugin | Any executable speaking the JSON plugin protocol |
|
|
61
|
+
|
|
62
|
+
Generated code is a thin facade over `codapact.runtime`: retries, auth, validation, and
|
|
63
|
+
pagination live in one tested place and improve without regenerating.
|
|
64
|
+
|
|
65
|
+
## Documents
|
|
66
|
+
|
|
67
|
+
- [Architecture](docs/architecture.md): layers, dependency rules, extension seams, and
|
|
68
|
+
lessons taken from Smithy, Fern, Kiota, protoc, Stainless, Speakeasy, graphql-codegen,
|
|
69
|
+
and restish.
|
|
70
|
+
- [Configuration](docs/configuration.md): `codapact.yaml`, shaping transforms, target
|
|
71
|
+
options, and generated CLI settings.
|
|
72
|
+
- [Contributing](CONTRIBUTING.md)
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: explanation
|
|
3
|
+
status: active
|
|
4
|
+
authority: normative
|
|
5
|
+
criticality: high
|
|
6
|
+
review:
|
|
7
|
+
status: unreviewed
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Architecture
|
|
11
|
+
|
|
12
|
+
CodaPact turns API contracts into libraries, then turns libraries into CLIs. Every stage
|
|
13
|
+
is a pure function over an explicit, serializable intermediate artifact. Each artifact can
|
|
14
|
+
be inspected (`codapact inspect …`), tested in isolation, and replaced without touching the
|
|
15
|
+
layers around it.
|
|
16
|
+
|
|
17
|
+
## Principles
|
|
18
|
+
|
|
19
|
+
1. **Semantics before protocol.** An operation's meaning (name, params, result, errors,
|
|
20
|
+
auth, pagination) is separate from how it travels (`HttpBinding`, `GraphQLBinding`).
|
|
21
|
+
Everything above the model works for any protocol that can be bound.
|
|
22
|
+
2. **The CLI is derived from the library, not from the contract.** The command model is
|
|
23
|
+
built from the library surface, so a CLI command always maps to exactly one library
|
|
24
|
+
method, with the same names, grouping, and flattening.
|
|
25
|
+
3. **Generated code is a facade.** Behavior (retries, auth, encoding, validation, paging)
|
|
26
|
+
lives in a versioned runtime. Fixes ship as a dependency bump, not a regeneration.
|
|
27
|
+
4. **Customize by configuration and overlays, not by editing output.** Shaping transforms
|
|
28
|
+
rename, group, filter, and annotate the model; the writer refuses to overwrite files it
|
|
29
|
+
does not own.
|
|
30
|
+
5. **Diagnostics, not exceptions or prints.** Each stage returns structured diagnostics
|
|
31
|
+
with stable codes and locations. Strict mode turns degradations into errors.
|
|
32
|
+
6. **Capabilities are negotiated.** The pipeline computes which features a model uses and
|
|
33
|
+
refuses to run a target that does not declare support for all of them.
|
|
34
|
+
|
|
35
|
+
## Layers
|
|
36
|
+
|
|
37
|
+
| Layer | Package | Input → output | Swappable unit |
|
|
38
|
+
| --- | --- | --- | --- |
|
|
39
|
+
| L0 acquire | `sources.loader` | path/URL → `SourceDocument` | `Fetcher` |
|
|
40
|
+
| L1 sources | `sources.openapi`, `sources.graphql` | document → `Api` | `Source` |
|
|
41
|
+
| L2 model | `model` | `Api` (+ JSON, validation, migrations) | none (the contract between layers) |
|
|
42
|
+
| L3 shaping | `shaping` | `Api` → `Api` + audit report | `Transform` |
|
|
43
|
+
| L4 surface | `surface` | `Api` → `Surface` (namespaces, methods, params) | `derive_surface` options |
|
|
44
|
+
| L5 commands | `commands` | `Api` + `Surface` → `CommandTree` | `derive_commands` |
|
|
45
|
+
| L6 targets | `targets.*`, `plugins` | `GenerationRequest` → files | `Target`, external plugin |
|
|
46
|
+
| L7 write | `pipeline.writer` | files → disk + ownership manifest | `plan`/`write` |
|
|
47
|
+
| runtime | `runtime` | used by generated Python code | `Transport`, `Middleware`, `AuthProvider`, `ProtocolAdapter` |
|
|
48
|
+
|
|
49
|
+
`pipeline` is the only composition root. `pipeline.defaults.default_registry()` is the one
|
|
50
|
+
place that names concrete implementations.
|
|
51
|
+
|
|
52
|
+
### Dependency rules
|
|
53
|
+
|
|
54
|
+
Enforced by `tests/unit/test_architecture.py` (AST import scan):
|
|
55
|
+
|
|
56
|
+
- `core` depends on nothing in the package.
|
|
57
|
+
- `model` depends only on `core`.
|
|
58
|
+
- `sources`, `shaping`, `surface` depend only on `core` and `model` (`commands` also on
|
|
59
|
+
`surface`).
|
|
60
|
+
- `runtime` depends only on `core` and `model`, so it can be split into its own
|
|
61
|
+
distribution.
|
|
62
|
+
- Each target depends on `plugins.protocol` and the layers below it, never on another
|
|
63
|
+
target or on `pipeline`.
|
|
64
|
+
- The root `codapact` package exports only `__version__`.
|
|
65
|
+
|
|
66
|
+
## The semantic model (L2)
|
|
67
|
+
|
|
68
|
+
- Types: `Record`, `Enum`, `Union` (optionally discriminated), `Alias`; expressions
|
|
69
|
+
`Primitive`, `Ref`, `ListOf`, `MapOf`, `Nullable`, `Literal`. Fields carry a `wire_name`,
|
|
70
|
+
so renames never change what goes on the wire.
|
|
71
|
+
- Operations: params, result, named error cases, auth requirement (alternatives of scheme
|
|
72
|
+
sets), pagination (cursor or offset), namespace, tags, and one or more bindings.
|
|
73
|
+
- Serialized as canonical JSON with `model_version`. `loads()` runs forward migrations
|
|
74
|
+
first, so artifacts and plugins written against an older version keep working.
|
|
75
|
+
- `validate()` checks unique names, resolvable references, identifier syntax, binding
|
|
76
|
+
consistency, declared auth schemes, and pagination parameters. The shaping engine runs it
|
|
77
|
+
after every step.
|
|
78
|
+
|
|
79
|
+
## Extension seams
|
|
80
|
+
|
|
81
|
+
| Seam | Protocol | Registered via |
|
|
82
|
+
| --- | --- | --- |
|
|
83
|
+
| Contract format | `Source.parse(SourceInput) -> SourceResult` | `Registry.add_source` |
|
|
84
|
+
| Model rewrite | `Transform.apply(api, config, diagnostics)` | `Registry.add_transform` |
|
|
85
|
+
| Language/output | `Target.generate(GenerationRequest) -> GenerationResponse` | `Registry.add_target` |
|
|
86
|
+
| Out-of-process target | `<cmd> describe` / `<cmd> generate` over stdin/stdout JSON | `plugin:` in config |
|
|
87
|
+
| HTTP sending | `Transport.send(HttpRequest)` | `RuntimeClient(transport=…)` |
|
|
88
|
+
| Cross-cutting | `Middleware(request, context, next)` | `RuntimeClient(middleware=…)` |
|
|
89
|
+
| Credentials | `AuthProvider.credential(scheme)` | `RuntimeClient(auth=…)` |
|
|
90
|
+
| Bespoke auth | `Authenticator.authenticate(request, scheme)`, optional `refresh` | returned by an `AuthProvider`; CLI `auth_plugin` |
|
|
91
|
+
| Protocol | `ProtocolAdapter.supports/call` | `RuntimeClient(adapters=…)` |
|
|
92
|
+
|
|
93
|
+
### Plugin protocol
|
|
94
|
+
|
|
95
|
+
- `describe` prints `{"name", "capabilities", "needs_commands"}`.
|
|
96
|
+
- `generate` reads a `GenerationRequest` (`protocol_version`, model, surface, optional
|
|
97
|
+
command tree, options) and prints a `GenerationResponse` (files + diagnostics).
|
|
98
|
+
- File paths are validated (relative, no `..`, no absolute or drive paths) before writing.
|
|
99
|
+
- Any language can implement a plugin; it never imports CodaPact internals.
|
|
100
|
+
|
|
101
|
+
### Capability negotiation
|
|
102
|
+
|
|
103
|
+
`required_capabilities(api)` yields tokens such as `binding:http`, `binding:graphql`,
|
|
104
|
+
`auth:bearer`, `pagination:cursor`, `type:union`, `type:map`, `type:literal`. A target
|
|
105
|
+
missing any token fails before generation with `CapabilityError`, rather than emitting code
|
|
106
|
+
that silently mishandles the feature.
|
|
107
|
+
|
|
108
|
+
## Runtime
|
|
109
|
+
|
|
110
|
+
- `RuntimeClient(api, base_url, auth, transport, middleware, adapters, …)`:
|
|
111
|
+
`call(operation, args)` encodes and validates arguments, picks the adapter for the
|
|
112
|
+
operation's binding, and decodes the result. `paginate()` follows cursors or offsets.
|
|
113
|
+
- `SafeHttpClient` (default transport): no redirects, bounded bodies, DNS pinned against
|
|
114
|
+
rebinding, private and plaintext addresses only with explicit opt-in.
|
|
115
|
+
- `Retry` middleware: idempotent operations only, exponential backoff, honors
|
|
116
|
+
`Retry-After`.
|
|
117
|
+
- Auth: sources (`StaticAuth`, `EnvAuth`, `ChainAuth`, `CommandAuth`, `StoreAuth`) return a
|
|
118
|
+
`Credential` or an `Authenticator`. `OAuth2` (in `runtime.oauth`) is an `Authenticator`
|
|
119
|
+
over a grant (client credentials, password, device code, authorization code + PKCE) and a
|
|
120
|
+
`TokenStore` (memory, file, keyring). Authenticators run after middleware; a 401 triggers
|
|
121
|
+
one `refresh()` and resend. `Credential.__repr__` never renders secrets.
|
|
122
|
+
- `runtime.selftest`: the suite generated bundles ship (offline dry runs, live scenarios).
|
|
123
|
+
- Errors: `ValidationError`, `AuthError`, `ApiError` (status, named error case, decoded
|
|
124
|
+
payload), `GraphQLResponseError`, `TransportError`.
|
|
125
|
+
|
|
126
|
+
## Lessons from existing tools
|
|
127
|
+
|
|
128
|
+
| Tool | What it does well | What CodaPact takes |
|
|
129
|
+
| --- | --- | --- |
|
|
130
|
+
| Smithy | Protocol-agnostic model; traits; projections | Semantics separate from bindings; shaping as projections over one model |
|
|
131
|
+
| Fern | Versioned IR consumed by generators | Serialized, versioned model with migrations; generators read IR, not contracts |
|
|
132
|
+
| Kiota | Abstractions package separate from HTTP implementation | Runtime seams (`Transport`, `AuthProvider`, `Middleware`) with swappable defaults |
|
|
133
|
+
| protoc | Plugins as executables over a request/response protocol | Out-of-process targets with a `describe`/`generate` handshake |
|
|
134
|
+
| Stainless | Config-driven resource grouping and naming; hand-edit safety | `group`/`rename` transforms; ownership manifest guards hand-written files |
|
|
135
|
+
| Speakeasy | Overlays; retries and pagination declared in config | `paginate` transform; idempotent-only retries with `Retry-After` |
|
|
136
|
+
| graphql-codegen | Exact result types per operation document | Selection-specific result types; `__typename`-discriminated unions |
|
|
137
|
+
| restish | Generic CLI from a contract at runtime | CLI is a thin layer over the same runtime the library uses |
|
|
138
|
+
|
|
139
|
+
Deliberate differences:
|
|
140
|
+
|
|
141
|
+
- One model for REST and GraphQL instead of one generator per protocol.
|
|
142
|
+
- CLI derived from the library surface, so the two cannot drift.
|
|
143
|
+
- Capability checks instead of best-effort output for unsupported features.
|
|
144
|
+
|
|
145
|
+
## Testing strategy
|
|
146
|
+
|
|
147
|
+
Summary; the full strategy, suites, and gates are in [testing](testing.md).
|
|
148
|
+
|
|
149
|
+
- Each layer has unit tests against hand-built inputs from the layer below.
|
|
150
|
+
- Property tests check translation against an independent JSON Schema oracle, and fuzz
|
|
151
|
+
whole contracts through every target.
|
|
152
|
+
- Generated Python and TypeScript are compiled, type-checked, and run against loopback
|
|
153
|
+
servers; the two runtimes must put identical requests on the wire.
|
|
154
|
+
- Real contracts (PokeAPI, YNAB) are generated in strict mode on every PR; public APIs are
|
|
155
|
+
called nightly.
|
|
@@ -1,3 +1,12 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: overview
|
|
3
|
+
status: active
|
|
4
|
+
authority: informative
|
|
5
|
+
criticality: low
|
|
6
|
+
review:
|
|
7
|
+
status: unreviewed
|
|
8
|
+
---
|
|
9
|
+
|
|
1
10
|
# CodaPact identity
|
|
2
11
|
|
|
3
12
|
**CodaPact** joins a musical coda, code, a contract, and the idea of impact.
|
|
@@ -16,8 +25,8 @@ music notes, terminal windows, and paperwork.
|
|
|
16
25
|
| Execution point | Amber `#d99732` |
|
|
17
26
|
| Supporting text | Slate `#52627a` |
|
|
18
27
|
|
|
19
|
-
Use [the wordmark](
|
|
20
|
-
[the standalone mark](
|
|
28
|
+
Use [the wordmark](wordmark.svg) on light backgrounds and
|
|
29
|
+
[the standalone mark](mark.svg) where space is limited. SVGs use
|
|
21
30
|
system fonts and contain no scripts, external resources, or embedded images.
|
|
22
31
|
|
|
23
32
|
Mike selected the name on 2026-10-29. Preliminary exact-name repository and
|