codapact 0.3.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.3.0 → codapact-0.4.0}/CHANGELOG.md +15 -0
- {codapact-0.3.0 → codapact-0.4.0}/PKG-INFO +2 -2
- {codapact-0.3.0 → codapact-0.4.0}/README.md +1 -1
- {codapact-0.3.0 → codapact-0.4.0}/docs/architecture.md +16 -7
- codapact-0.4.0/docs/configuration.md +276 -0
- codapact-0.4.0/docs/testing.md +90 -0
- {codapact-0.3.0 → codapact-0.4.0}/pyproject.toml +64 -3
- 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.3.0 → codapact-0.4.0}/src/codapact/__init__.py +1 -1
- codapact-0.4.0/src/codapact/__main__.py +5 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/commands/derive.py +90 -2
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/commands/model.py +11 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/naming.py +5 -0
- codapact-0.4.0/src/codapact/core/net.py +254 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/__init__.py +6 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/api.py +70 -6
- codapact-0.4.0/src/codapact/model/authspec.py +98 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/migrations.py +22 -1
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/rewrite.py +25 -1
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/serialize.py +1 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/validate.py +1 -3
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/cli.py +10 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/config.py +17 -1
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/pipeline.py +31 -5
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/protocol.py +3 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/__init__.py +27 -1
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/abstractions.py +28 -2
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/arguments.py +5 -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.3.0 → codapact-0.4.0}/src/codapact/runtime/client.py +28 -4
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/codec.py +88 -0
- codapact-0.4.0/src/codapact/runtime/credentials.py +331 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/errors.py +22 -0
- codapact-0.4.0/src/codapact/runtime/oauth.py +849 -0
- codapact-0.4.0/src/codapact/runtime/protocols/base.py +113 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/protocols/graphql.py +3 -1
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/protocols/http.py +31 -8
- codapact-0.4.0/src/codapact/runtime/selftest.py +339 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/transforms.py +236 -44
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/graphql/translator.py +108 -15
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/loader.py +58 -19
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/openapi/translator.py +179 -26
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/surface/derive.py +126 -23
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/surface/model.py +19 -1
- 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.3.0 → codapact-0.4.0}/src/codapact/targets/python/library.py +57 -13
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/typescript/library.py +60 -9
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/typescript/runtime.ts +201 -23
- 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/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.3.0/tests → codapact-0.4.0/tests/integration}/test_generation.py +10 -39
- 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.3.0 → codapact-0.4.0}/tests/support.py +204 -1
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_architecture.py +3 -1
- 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_guards.py +233 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_model.py +28 -1
- 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.3.0/tests → codapact-0.4.0/tests/unit}/test_openapi_edges.py +164 -3
- codapact-0.4.0/tests/unit/test_openapi_translator_units.py +388 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_plugins_pipeline.py +3 -3
- codapact-0.4.0/tests/unit/test_public_api_findings.py +932 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_runtime_edges.py +22 -3
- codapact-0.4.0/tests/unit/test_runtime_pagination.py +116 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_sources.py +42 -2
- 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.3.0 → codapact-0.4.0}/uv.lock +516 -1
- codapact-0.3.0/.github/workflows/ci.yml +0 -53
- codapact-0.3.0/.release-please-manifest.json +0 -1
- codapact-0.3.0/docs/configuration.md +0 -91
- codapact-0.3.0/pyproject.toml.orig +0 -79
- codapact-0.3.0/src/codapact/core/net.py +0 -121
- codapact-0.3.0/src/codapact/runtime/auth.py +0 -113
- codapact-0.3.0/src/codapact/runtime/cli.py +0 -196
- codapact-0.3.0/src/codapact/runtime/protocols/base.py +0 -59
- codapact-0.3.0/src/codapact/targets/python/cli.py +0 -189
- {codapact-0.3.0 → codapact-0.4.0}/.github/workflows/codeql.yml +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/.github/workflows/release.yml +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/LICENSE +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/docs/branding/README.md +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/docs/branding/mark.svg +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/docs/branding/wordmark.svg +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/examples/library/codapact.yaml +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/examples/library/operations.graphql +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/examples/library/schema.graphql +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/examples/petstore/codapact.yaml +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/examples/petstore/openapi.yaml +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/release-please-config.json +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/scripts/verify_dist.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/commands/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/diagnostics.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/errors.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/types.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/values.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/defaults.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/writer.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/external.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/registry.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/py.typed +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/middleware.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/protocols/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/base.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/engine.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/base.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/graphql/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/openapi/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/surface/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/python/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/python/naming.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/typescript/__init__.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/tests/fixtures/library_smoke.ts +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/tests/fixtures/outline_plugin.py +0 -0
- {codapact-0.3.0 → codapact-0.4.0}/tests/fixtures/petstore_smoke.ts +0 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_codec_serialize.py +0 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_core.py +0 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_runtime.py +0 -0
- {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_shaping_surface_commands.py +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,21 @@
|
|
|
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
|
+
|
|
5
20
|
## [0.3.0](https://github.com/mikejhill/codapact/compare/v0.2.0...v0.3.0) (2026-11-10)
|
|
6
21
|
|
|
7
22
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: codapact
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: Contracts into callable tools: generate libraries, then CLIs, from OpenAPI, GraphQL, and other API contracts.
|
|
5
5
|
License-Expression: MIT
|
|
6
6
|
License-File: LICENSE
|
|
@@ -70,7 +70,7 @@ uv run codapact inspect commands -c examples/library/codapact.yaml
|
|
|
70
70
|
| Output | Contents |
|
|
71
71
|
| --- | --- |
|
|
72
72
|
| `python` | Installable package: `TypedDict` types, a resource-per-namespace client, paging iterators, `py.typed` |
|
|
73
|
-
| `python-cli` | argparse CLI calling the Python library
|
|
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
74
|
| `typescript` | Fetch-based client with bundled runtime; strict `tsc` clean |
|
|
75
75
|
| external plugin | Any executable speaking the JSON plugin protocol |
|
|
76
76
|
|
|
@@ -55,7 +55,7 @@ uv run codapact inspect commands -c examples/library/codapact.yaml
|
|
|
55
55
|
| Output | Contents |
|
|
56
56
|
| --- | --- |
|
|
57
57
|
| `python` | Installable package: `TypedDict` types, a resource-per-namespace client, paging iterators, `py.typed` |
|
|
58
|
-
| `python-cli` | argparse CLI calling the Python library
|
|
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
59
|
| `typescript` | Fetch-based client with bundled runtime; strict `tsc` clean |
|
|
60
60
|
| external plugin | Any executable speaking the JSON plugin protocol |
|
|
61
61
|
|
|
@@ -51,7 +51,7 @@ place that names concrete implementations.
|
|
|
51
51
|
|
|
52
52
|
### Dependency rules
|
|
53
53
|
|
|
54
|
-
Enforced by `tests/test_architecture.py` (AST import scan):
|
|
54
|
+
Enforced by `tests/unit/test_architecture.py` (AST import scan):
|
|
55
55
|
|
|
56
56
|
- `core` depends on nothing in the package.
|
|
57
57
|
- `model` depends only on `core`.
|
|
@@ -87,6 +87,7 @@ Enforced by `tests/test_architecture.py` (AST import scan):
|
|
|
87
87
|
| HTTP sending | `Transport.send(HttpRequest)` | `RuntimeClient(transport=…)` |
|
|
88
88
|
| Cross-cutting | `Middleware(request, context, next)` | `RuntimeClient(middleware=…)` |
|
|
89
89
|
| Credentials | `AuthProvider.credential(scheme)` | `RuntimeClient(auth=…)` |
|
|
90
|
+
| Bespoke auth | `Authenticator.authenticate(request, scheme)`, optional `refresh` | returned by an `AuthProvider`; CLI `auth_plugin` |
|
|
90
91
|
| Protocol | `ProtocolAdapter.supports/call` | `RuntimeClient(adapters=…)` |
|
|
91
92
|
|
|
92
93
|
### Plugin protocol
|
|
@@ -113,8 +114,12 @@ that silently mishandles the feature.
|
|
|
113
114
|
rebinding, private and plaintext addresses only with explicit opt-in.
|
|
114
115
|
- `Retry` middleware: idempotent operations only, exponential backoff, honors
|
|
115
116
|
`Retry-After`.
|
|
116
|
-
- Auth: `StaticAuth`, `EnvAuth
|
|
117
|
-
|
|
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).
|
|
118
123
|
- Errors: `ValidationError`, `AuthError`, `ApiError` (status, named error case, decoded
|
|
119
124
|
payload), `GraphQLResponseError`, `TransportError`.
|
|
120
125
|
|
|
@@ -139,8 +144,12 @@ Deliberate differences:
|
|
|
139
144
|
|
|
140
145
|
## Testing strategy
|
|
141
146
|
|
|
147
|
+
Summary; the full strategy, suites, and gates are in [testing](testing.md).
|
|
148
|
+
|
|
142
149
|
- Each layer has unit tests against hand-built inputs from the layer below.
|
|
143
|
-
-
|
|
144
|
-
|
|
145
|
-
- Generated Python
|
|
146
|
-
|
|
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.
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: reference
|
|
3
|
+
status: active
|
|
4
|
+
authority: normative
|
|
5
|
+
criticality: normal
|
|
6
|
+
review:
|
|
7
|
+
status: unreviewed
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Configuration
|
|
11
|
+
|
|
12
|
+
## `codapact.yaml`
|
|
13
|
+
|
|
14
|
+
```yaml
|
|
15
|
+
version: 1
|
|
16
|
+
source:
|
|
17
|
+
type: openapi # openapi | graphql
|
|
18
|
+
path: openapi.yaml # local path (relative to this file) or https URL
|
|
19
|
+
documents: [] # companion documents, e.g. GraphQL operations
|
|
20
|
+
options: {strict: true}
|
|
21
|
+
shape: # ordered transforms; the model is re-validated after each
|
|
22
|
+
- group: {by: tag}
|
|
23
|
+
- paginate: {operations: [list_pets], next: next_cursor, items: items}
|
|
24
|
+
surface: {flatten_body: true, trim_namespace: true}
|
|
25
|
+
cli:
|
|
26
|
+
program: petstore
|
|
27
|
+
auth_plugin: my_auth:provider # optional; see Authentication
|
|
28
|
+
auth: {sso: {client_id: petstore-cli, scopes: [read]}}
|
|
29
|
+
e2e: # optional; tests shipped with the generated CLI
|
|
30
|
+
scenarios:
|
|
31
|
+
- {name: list pets, run: [pets, list], expect: {not_empty: ["$"]}}
|
|
32
|
+
targets:
|
|
33
|
+
- {name: python, output: out/python, options: {package: petstore}}
|
|
34
|
+
- {name: python-cli, output: out/python}
|
|
35
|
+
- {name: typescript, output: out/ts, options: {package: petstore}}
|
|
36
|
+
- {plugin: [python, my_plugin.py], output: out/custom}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Targets that share an `output` directory share options. When `python-cli` shares the
|
|
40
|
+
`python` directory, the library's `pyproject.toml` gains the CLI script entry.
|
|
41
|
+
|
|
42
|
+
## Sources
|
|
43
|
+
|
|
44
|
+
| Source | Option | Default | Meaning |
|
|
45
|
+
| --- | --- | --- | --- |
|
|
46
|
+
| both | `strict` | `true` | Unsupported features are errors; when `false`, they degrade with a warning. For GraphQL, `false` also builds schemas that break spec rules (as GitHub's does) and lists the problems as warnings |
|
|
47
|
+
| `graphql` | `name` | `GraphQL API` | API name |
|
|
48
|
+
| `graphql` | `version` | empty | API version |
|
|
49
|
+
| `graphql` | `url` | none | Endpoint; becomes the default server |
|
|
50
|
+
| `graphql` | `auth` | none | `bearer`, `basic`, `{api_key: HEADER}`, or `{schemes: {NAME: SPEC}}` with any [auth spec](#auth-specs); required on every operation |
|
|
51
|
+
| `graphql` | `depth` | `1` | Object nesting synthesized in schema mode (0–8) |
|
|
52
|
+
|
|
53
|
+
`source.max_bytes` (next to `type` and `path`, not under `options`) caps each contract
|
|
54
|
+
document; the default is 64 MB. Remote contracts and generated clients honour
|
|
55
|
+
`HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`. Proxy URLs must use `http://` without
|
|
56
|
+
credentials; HTTPS traffic is tunnelled with `CONNECT`.
|
|
57
|
+
|
|
58
|
+
GraphQL with `documents` generates one operation per document operation with exact result
|
|
59
|
+
types. Without documents, it generates one operation per root field. A `#` comment block
|
|
60
|
+
directly above a document operation becomes its description; variable defaults
|
|
61
|
+
(`$first: Int = 5`) become parameter defaults.
|
|
62
|
+
|
|
63
|
+
When the first shaping step is `select`, model errors in operations it removes are reported
|
|
64
|
+
as one warning instead of blocking generation.
|
|
65
|
+
|
|
66
|
+
## Shaping transforms
|
|
67
|
+
|
|
68
|
+
| Transform | Config |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| `select` | `include`, `exclude`: lists of globs or `{name, tag, kind, namespace, read_only}` selectors |
|
|
71
|
+
| `rename` | `operations`, `types`, `fields` (`Type.field`), `params` (`op.param`), `patterns` (`[{match: regex, replace: template}]` over operation names; explicit `operations` entries win); wire names are kept |
|
|
72
|
+
| `group` | `by: tag` or `by: path`, and/or `operations: {glob: dotted.namespace}` |
|
|
73
|
+
| `paginate` | `operations`, `style: cursor` (`param`, `next`), `offset` (`param`, `limit_param`), or `page` (`param`, default `page`; `start`, default `1`), and `items` (`$` when the result itself is the list). Operations matched only by a pattern that lack the param or items are skipped with a warning; operations named exactly are errors |
|
|
74
|
+
| `defaults` | `params: {"op_glob.param": value}`; the param becomes optional and the runtime sends `value` when it is omitted |
|
|
75
|
+
| `auth` | `schemes: {name: SPEC}` ([auth specs](#auth-specs)), `operations` (default all), `optional` (send credentials when set, call anonymously otherwise). For contracts that omit or under-declare `securitySchemes`; re-declaring an identical scheme is allowed |
|
|
76
|
+
| `prune` | none; removes unreachable types (also run by `select`) |
|
|
77
|
+
|
|
78
|
+
## Surface options
|
|
79
|
+
|
|
80
|
+
| Option | Default | Meaning |
|
|
81
|
+
| --- | --- | --- |
|
|
82
|
+
| `flatten_body` | `true` | Expose record body fields as individual method params |
|
|
83
|
+
| `flatten_wrapper` | `true` | A required body `{"account": {...}}` with one record field exposes that record's fields |
|
|
84
|
+
| `trim_namespace` | `true` | `pets.list_pets` becomes `pets.list`; a noun phrase ending in the namespace is dropped (`months.get_plan_months` → `months.list`); a plural/singular clash yields `update` and `update_many`; names that would still collide are kept |
|
|
85
|
+
| `conventional_names` | `true` | `get_<plural>` becomes `list_<plural>`; a trailing `by_id` is dropped (`get_pet_by_id` → `get_pet`) |
|
|
86
|
+
|
|
87
|
+
## Targets
|
|
88
|
+
|
|
89
|
+
| Target | Option | Default |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| `python` | `package` | from API name |
|
|
92
|
+
| `python` | `distribution` | package with `-` |
|
|
93
|
+
| `python` | `version` | `0.1.0` |
|
|
94
|
+
| `typescript` | `package` | API name in kebab case |
|
|
95
|
+
| `typescript` | `version` | `0.1.0` |
|
|
96
|
+
|
|
97
|
+
## Generated CLI settings
|
|
98
|
+
|
|
99
|
+
Precedence: flag, then environment, then settings file.
|
|
100
|
+
|
|
101
|
+
| Setting | Flag | Environment | File key |
|
|
102
|
+
| --- | --- | --- | --- |
|
|
103
|
+
| Base URL | `--base-url` | `<PREFIX>_BASE_URL` | `base_url` |
|
|
104
|
+
| Timeout | `--timeout` | `<PREFIX>_TIMEOUT` | `timeout` |
|
|
105
|
+
| Private network | `--allow-private` | `<PREFIX>_ALLOW_PRIVATE` | `allow_private` |
|
|
106
|
+
| Response validation | `--response-validation strict\|warn\|off` | `<PREFIX>_RESPONSE_VALIDATION` | `response_validation` |
|
|
107
|
+
| Output format | `-o`/`--output json\|jsonl\|yaml\|table\|raw` | `<PREFIX>_OUTPUT` | `output` |
|
|
108
|
+
| Error format | `--error-format text\|json` | `<PREFIX>_ERROR_FORMAT` | `error_format` |
|
|
109
|
+
| Credentials | none | `<PREFIX>_<SCHEME>`; basic uses `_USERNAME`/`_PASSWORD`; full chain under [Authentication](#authentication) | `auth_plugin`; secrets are never read from the file |
|
|
110
|
+
| Option defaults | the option itself | none | `defaults: {plan_id: "…"}` (option names, `_` or `-`) |
|
|
111
|
+
|
|
112
|
+
The settings file is `--config PATH` or `$XDG_CONFIG_HOME/<program>/config.json`.
|
|
113
|
+
`<PREFIX>` is the program name in upper snake case. `<program> --help` lists the
|
|
114
|
+
credential variables for the contract's auth schemes.
|
|
115
|
+
|
|
116
|
+
Global options work before or after the command: `--base-url`, `--timeout`, `--config`,
|
|
117
|
+
`-o/--output`, `--query PATH` (`data.items[].name`, `data.items[0]`; with `--all` the
|
|
118
|
+
result is the item list, so `[].name`), `--dry-run`, `-v/--verbose`, `--error-format`,
|
|
119
|
+
`--allow-private`, and `--response-validation`. Command help lists them in one line;
|
|
120
|
+
`<program> --help` describes each.
|
|
121
|
+
`table` renders a list of objects, unwrapping single-list envelopes such as `{"data": {"items": [...]}}`.
|
|
122
|
+
`jsonl` prints one JSON value per line and streams `--all` results page by page.
|
|
123
|
+
|
|
124
|
+
### Conventions every generated CLI follows
|
|
125
|
+
|
|
126
|
+
| Need | How |
|
|
127
|
+
| --- | --- |
|
|
128
|
+
| Help | `-h`/`--help` on every level; bare `<program>` or `<program> GROUP` prints help (exit `0`). Command help has a usage line with positionals and required options, examples, and a global-options reminder. |
|
|
129
|
+
| Version | `-V`/`--version`: `poke 0.1.0 (PokéAPI 2.10.0; codapact 0.4.0)` |
|
|
130
|
+
| Discovery for agents | `<program> describe [COMMAND…]`: JSON with every command's arguments (type, required, positional, choices, repeated), `read_only`/`destructive`/`paginated`, `requires_one_of` option groups, environment variables, exit codes. `describe --brief` keeps only names, summaries, and usage lines. Naming one command (or passing `--schemas`) adds the JSON Schema of its output and of each JSON-valued argument |
|
|
131
|
+
| Diagnosis | `<program> doctor [--offline]`: version, settings file, base URL and its source, credentials (set or missing, never printed), proxy, connectivity. Table on a terminal, JSON otherwise; exit `1` when a check fails |
|
|
132
|
+
| Completion | `<program> completion bash\|zsh\|fish\|powershell` prints a script that asks the program for candidates |
|
|
133
|
+
| Preview | `--dry-run` prints the HTTP request (method, URL, headers, body) without sending it; credentials appear as `$VARIABLE` placeholders (optional credentials that are not set stay off the request), and destructive commands skip confirmation |
|
|
134
|
+
| Tracing | `-v`/`--verbose` logs each request line and response status, size, and time to stderr, masking credential values |
|
|
135
|
+
| Mistakes | unknown commands, choices, and options get "did you mean" hints; leftovers are reported by the command they were given to; API failures name the command typed (`pets get failed with HTTP 404`) |
|
|
136
|
+
| Machine-readable errors | `--error-format json` prints one `{"error": {"type", "message", "exit_code", "status", "hint", "details"}}` object on stderr; contract warnings become `{"warning": …}` lines |
|
|
137
|
+
|
|
138
|
+
| Credentials | `<program> auth login\|logout\|status\|token`; see [Authentication](#authentication) |
|
|
139
|
+
|
|
140
|
+
`describe`, `doctor`, `completion`, and `auth` are skipped when the API has a top-level command
|
|
141
|
+
of the same name; `--version`, `--dry-run`, `--verbose`, and `--error-format` are reserved, so
|
|
142
|
+
API parameters with those names become `--arg-version` and so on.
|
|
143
|
+
|
|
144
|
+
`tests/integration/test_cli_conformance.py` checks these conventions for every example
|
|
145
|
+
contract (Petstore, Library, PokéAPI, YNAB, Countries), including a `--dry-run` of every
|
|
146
|
+
command built from its own `describe` entry.
|
|
147
|
+
|
|
148
|
+
Commands for HTTP `DELETE` operations, or operations named `delete_*`/`remove_*`/`destroy_*`/`purge_*`,
|
|
149
|
+
ask for confirmation on a terminal and require `--yes` otherwise.
|
|
150
|
+
|
|
151
|
+
Validation errors name the command-line option (`--amount: expected an integer`).
|
|
152
|
+
|
|
153
|
+
Required path parameters without a default are positional, in URL order
|
|
154
|
+
(`repos get OWNER REPO`); the `--owner` form still works.
|
|
155
|
+
|
|
156
|
+
Responses that break the contract (a `null` where the contract promises a string) print
|
|
157
|
+
a warning and the data by default (`warn`). `strict` fails with exit `1`; `off` skips
|
|
158
|
+
response checks. Generated libraries default to `strict` and raise
|
|
159
|
+
`ResponseValidationError`, whose `data` holds the response.
|
|
160
|
+
|
|
161
|
+
Exit codes: `0` success, `1` API error or contract break, `2` usage or validation, `3` auth
|
|
162
|
+
(missing credentials or HTTP 401/403), `4` transport, `130` interrupted. Root help and
|
|
163
|
+
`describe` list them.
|
|
164
|
+
|
|
165
|
+
## Authentication
|
|
166
|
+
|
|
167
|
+
Three layers, each usable without the next:
|
|
168
|
+
|
|
169
|
+
| Layer | What it is | Use it for |
|
|
170
|
+
| --- | --- | --- |
|
|
171
|
+
| Source | `AuthProvider.credential(scheme) -> Credential \| Authenticator \| None` | Where a secret comes from: environment, a command, the OS keyring, a vault |
|
|
172
|
+
| Built-in flow | `OAuth2(grant, store)` with `ClientCredentials`, `PasswordGrant`, `DeviceCode` (RFC 8628), `AuthorizationCodePKCE` (loopback redirect); refresh tokens; OIDC discovery | Standard OAuth 2.0 / OpenID Connect without code |
|
|
173
|
+
| Bespoke | `Authenticator.authenticate(request, scheme) -> request`, optional `refresh(scheme) -> bool` | Request signing (HMAC, AWS SigV4), token exchange, anything else |
|
|
174
|
+
|
|
175
|
+
An `Authenticator` runs last, after middleware, so a retried request is signed again. On
|
|
176
|
+
HTTP 401 the runtime calls `refresh()` and, if it returns true, sends the request once more.
|
|
177
|
+
|
|
178
|
+
### Auth specs
|
|
179
|
+
|
|
180
|
+
Used by the `auth` transform, the GraphQL `auth` option, and `cli.auth`:
|
|
181
|
+
|
|
182
|
+
| Spec | Meaning |
|
|
183
|
+
| --- | --- |
|
|
184
|
+
| `bearer`, `basic` | `Authorization` header |
|
|
185
|
+
| `{api_key: NAME, in: header\|query\|cookie}` | key sent under `NAME` |
|
|
186
|
+
| `oauth2` | bearer token; flows come from settings or `auth login` |
|
|
187
|
+
| `{oauth2: {client_credentials\|authorization_code\|device_code\|password: {token_url, authorization_url, device_authorization_url, refresh_url, scopes}}}` | OAuth 2.0 with known endpoints |
|
|
188
|
+
| `{openid: DISCOVERY_URL}` | OAuth 2.0 whose endpoints come from `.well-known/openid-configuration` |
|
|
189
|
+
| `custom` or `{custom: DESCRIPTION}` | needs an `Authenticator` (plugin or library code) |
|
|
190
|
+
|
|
191
|
+
Any spec map also takes `docs`. OpenAPI `oauth2` (including 3.2 `deviceAuthorization`) and
|
|
192
|
+
`openIdConnect` map to the same model; other schemes (`mutualTLS`, `http` with an unknown
|
|
193
|
+
scheme) become `custom` with an info diagnostic.
|
|
194
|
+
|
|
195
|
+
### CLI credential chain
|
|
196
|
+
|
|
197
|
+
The first source that has a credential wins, per scheme:
|
|
198
|
+
|
|
199
|
+
1. Plugin: `<PREFIX>_AUTH_PLUGIN`, settings file `auth_plugin`, or `cli.auth_plugin`,
|
|
200
|
+
as `module:function`. The function takes an `AuthContext` (`api`, `program`,
|
|
201
|
+
`env_prefix`, `environ`, `store`, `http`) and returns an `AuthProvider` or a
|
|
202
|
+
`{scheme: Credential | Authenticator | str}` map.
|
|
203
|
+
2. Environment: `<PREFIX>_<SCHEME>` (basic: `_USERNAME`, `_PASSWORD`).
|
|
204
|
+
3. Command: `<PREFIX>_<SCHEME>_COMMAND`, run without a shell; stdout is the secret
|
|
205
|
+
(`op read …`, `vault kv get …`, `gh auth token`).
|
|
206
|
+
4. OAuth client: `<PREFIX>_<SCHEME>_CLIENT_ID` + `_CLIENT_SECRET` (optional `_SCOPES`)
|
|
207
|
+
runs the client-credentials grant and caches the token.
|
|
208
|
+
5. Saved login from `<program> auth login`.
|
|
209
|
+
|
|
210
|
+
`cli.auth: {SCHEME: {client_id, scopes, flow, audience}}` bakes public OAuth settings into
|
|
211
|
+
the CLI (no secrets). `auth login` picks a flow in this order: `--flow`, then client
|
|
212
|
+
credentials when a secret is set, then device code, then authorization code with PKCE.
|
|
213
|
+
`--with-token` reads a static token from stdin; `--username` saves basic credentials.
|
|
214
|
+
`auth status` shows each scheme's source; `auth token` prints what a command would send;
|
|
215
|
+
`doctor` reports the same, never printing secrets.
|
|
216
|
+
|
|
217
|
+
Saved credentials and tokens go to the OS keyring when one is usable, otherwise to a
|
|
218
|
+
`0600` JSON file at `$XDG_CONFIG_HOME/<program>/credentials.json`.
|
|
219
|
+
`<PREFIX>_CREDENTIAL_STORE=keyring|file|memory` forces one.
|
|
220
|
+
|
|
221
|
+
Libraries take the same objects directly:
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
from codapact.runtime import ClientCredentials, OAuth2, StaticAuth
|
|
225
|
+
|
|
226
|
+
client = Client(
|
|
227
|
+
auth=StaticAuth(
|
|
228
|
+
{
|
|
229
|
+
"token": "…", # bearer / api key
|
|
230
|
+
"sso": OAuth2(ClientCredentials(token_url, client_id, secret)),
|
|
231
|
+
"signed": HmacSigner(key_id, secret), # your Authenticator
|
|
232
|
+
}
|
|
233
|
+
)
|
|
234
|
+
)
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The TypeScript client accepts a string, `{username, password}`, a token function, an
|
|
238
|
+
`Authenticator` object, or `clientCredentials({tokenUrl, clientId, clientSecret})`.
|
|
239
|
+
|
|
240
|
+
## Generated bundle tests
|
|
241
|
+
|
|
242
|
+
`python-cli` writes `tests/test_e2e.py` and `tests/e2e.json` into the bundle
|
|
243
|
+
(`options: {tests: false}` turns this off). Run them with `uv run pytest` in the bundle.
|
|
244
|
+
|
|
245
|
+
| Tier | Runs | Checks |
|
|
246
|
+
| --- | --- | --- |
|
|
247
|
+
| Offline | always | `--help` of every command; a `--dry-run` of every command with sampled arguments: method, path, and where each credential goes |
|
|
248
|
+
| Live | `<PREFIX>_E2E_LIVE=1` (or `CODAPACT_LIVE=1`) | `e2e.scenarios`, then a smoke call of each read-only command that needs no arguments |
|
|
249
|
+
|
|
250
|
+
A live case whose credentials are not configured is skipped;
|
|
251
|
+
`<PREFIX>_E2E_REQUIRE_AUTH=1` makes it fail instead.
|
|
252
|
+
|
|
253
|
+
| `e2e` key | Meaning |
|
|
254
|
+
| --- | --- |
|
|
255
|
+
| `scenarios` | list of `{name, run, auth, expect, env, response_validation, stdin}`; `run` is the argument list after the program name |
|
|
256
|
+
| `scenarios[].auth` | `any` (default), `required` (skip without credentials), `none` (run with every credential removed) |
|
|
257
|
+
| `scenarios[].expect` | `exit` (default `0`), `contains: {PATH: value}` (subset match), `not_empty: [PATH]`, `at_least: {PATH: n}`, `length_at_least: {PATH: n}`, `stderr_contains`; `PATH` uses the `--query` syntax, `$` is the whole result |
|
|
258
|
+
| `smoke` | `true` (default), `false`, or `{limit: 25, exclude: [glob]}` over command paths |
|
|
259
|
+
| `response_validation` | mode for every live case (default `strict`) |
|
|
260
|
+
|
|
261
|
+
## Generated names by target
|
|
262
|
+
|
|
263
|
+
| Target | Method params | Record fields |
|
|
264
|
+
| --- | --- | --- |
|
|
265
|
+
| Python | `snake_case` (keywords get a trailing `_`) | model names; the runtime codec maps them to wire names |
|
|
266
|
+
| TypeScript | `camelCase` | wire names; the bundled runtime sends values as typed, without a codec |
|
|
267
|
+
|
|
268
|
+
So `rename.fields` renames a Python `TypedDict` key but not a TypeScript type key. Method
|
|
269
|
+
parameters follow each language's convention in both targets.
|
|
270
|
+
|
|
271
|
+
## Formats
|
|
272
|
+
|
|
273
|
+
`format` values (`date`, `date-time`, `uuid`, …) are annotations, as in JSON Schema 2020-12:
|
|
274
|
+
the client does not reject values that do not match them, because real APIs accept extra
|
|
275
|
+
forms (YNAB's `month` path param is `format: date` but also takes `current`). CLIs show
|
|
276
|
+
`YYYY-MM-DD` / `DATETIME` as the option placeholder.
|