codapact 0.1.1__tar.gz → 0.3.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.
Files changed (151) hide show
  1. codapact-0.3.0/.release-please-manifest.json +1 -0
  2. {codapact-0.1.1 → codapact-0.3.0}/CHANGELOG.md +26 -0
  3. codapact-0.3.0/PKG-INFO +87 -0
  4. codapact-0.3.0/README.md +72 -0
  5. codapact-0.3.0/docs/architecture.md +146 -0
  6. codapact-0.1.1/docs/branding.md → codapact-0.3.0/docs/branding/README.md +11 -2
  7. codapact-0.3.0/docs/configuration.md +91 -0
  8. codapact-0.3.0/examples/library/codapact.yaml +20 -0
  9. codapact-0.3.0/examples/library/operations.graphql +13 -0
  10. codapact-0.3.0/examples/library/schema.graphql +49 -0
  11. codapact-0.3.0/examples/petstore/codapact.yaml +23 -0
  12. codapact-0.3.0/examples/petstore/openapi.yaml +131 -0
  13. {codapact-0.1.1 → codapact-0.3.0}/pyproject.toml +19 -27
  14. {codapact-0.1.1 → codapact-0.3.0}/pyproject.toml.orig +20 -16
  15. codapact-0.3.0/src/codapact/__init__.py +8 -0
  16. codapact-0.3.0/src/codapact/commands/__init__.py +1 -0
  17. codapact-0.3.0/src/codapact/commands/derive.py +118 -0
  18. codapact-0.3.0/src/codapact/commands/model.py +77 -0
  19. codapact-0.3.0/src/codapact/core/__init__.py +5 -0
  20. codapact-0.3.0/src/codapact/core/diagnostics.py +109 -0
  21. codapact-0.3.0/src/codapact/core/errors.py +48 -0
  22. codapact-0.3.0/src/codapact/core/naming.py +68 -0
  23. codapact-0.3.0/src/codapact/core/net.py +121 -0
  24. codapact-0.3.0/src/codapact/model/__init__.py +86 -0
  25. codapact-0.3.0/src/codapact/model/api.py +224 -0
  26. codapact-0.3.0/src/codapact/model/migrations.py +37 -0
  27. codapact-0.3.0/src/codapact/model/rewrite.py +71 -0
  28. codapact-0.3.0/src/codapact/model/serialize.py +207 -0
  29. codapact-0.3.0/src/codapact/model/types.py +196 -0
  30. codapact-0.3.0/src/codapact/model/validate.py +142 -0
  31. codapact-0.3.0/src/codapact/model/values.py +5 -0
  32. codapact-0.3.0/src/codapact/pipeline/__init__.py +1 -0
  33. codapact-0.3.0/src/codapact/pipeline/cli.py +126 -0
  34. codapact-0.3.0/src/codapact/pipeline/config.py +135 -0
  35. codapact-0.3.0/src/codapact/pipeline/defaults.py +31 -0
  36. codapact-0.3.0/src/codapact/pipeline/pipeline.py +154 -0
  37. codapact-0.3.0/src/codapact/pipeline/writer.py +133 -0
  38. codapact-0.3.0/src/codapact/plugins/__init__.py +1 -0
  39. codapact-0.3.0/src/codapact/plugins/external.py +77 -0
  40. codapact-0.3.0/src/codapact/plugins/protocol.py +195 -0
  41. codapact-0.3.0/src/codapact/plugins/registry.py +61 -0
  42. codapact-0.3.0/src/codapact/runtime/__init__.py +48 -0
  43. codapact-0.3.0/src/codapact/runtime/abstractions.py +86 -0
  44. codapact-0.3.0/src/codapact/runtime/arguments.py +45 -0
  45. codapact-0.3.0/src/codapact/runtime/auth.py +113 -0
  46. codapact-0.3.0/src/codapact/runtime/cli.py +196 -0
  47. codapact-0.3.0/src/codapact/runtime/client.py +151 -0
  48. codapact-0.3.0/src/codapact/runtime/codec.py +191 -0
  49. codapact-0.3.0/src/codapact/runtime/errors.py +62 -0
  50. codapact-0.3.0/src/codapact/runtime/middleware.py +66 -0
  51. codapact-0.3.0/src/codapact/runtime/protocols/__init__.py +1 -0
  52. codapact-0.3.0/src/codapact/runtime/protocols/base.py +59 -0
  53. codapact-0.3.0/src/codapact/runtime/protocols/graphql.py +63 -0
  54. codapact-0.3.0/src/codapact/runtime/protocols/http.py +132 -0
  55. codapact-0.3.0/src/codapact/shaping/__init__.py +1 -0
  56. codapact-0.3.0/src/codapact/shaping/base.py +36 -0
  57. codapact-0.3.0/src/codapact/shaping/engine.py +60 -0
  58. codapact-0.3.0/src/codapact/shaping/transforms.py +329 -0
  59. codapact-0.3.0/src/codapact/sources/__init__.py +1 -0
  60. codapact-0.3.0/src/codapact/sources/base.py +53 -0
  61. codapact-0.3.0/src/codapact/sources/graphql/__init__.py +5 -0
  62. codapact-0.3.0/src/codapact/sources/graphql/translator.py +555 -0
  63. codapact-0.3.0/src/codapact/sources/loader.py +112 -0
  64. codapact-0.3.0/src/codapact/sources/openapi/__init__.py +5 -0
  65. codapact-0.3.0/src/codapact/sources/openapi/translator.py +721 -0
  66. codapact-0.3.0/src/codapact/surface/__init__.py +1 -0
  67. codapact-0.3.0/src/codapact/surface/derive.py +190 -0
  68. codapact-0.3.0/src/codapact/surface/model.py +91 -0
  69. codapact-0.3.0/src/codapact/targets/__init__.py +1 -0
  70. codapact-0.3.0/src/codapact/targets/python/__init__.py +1 -0
  71. codapact-0.3.0/src/codapact/targets/python/cli.py +189 -0
  72. codapact-0.3.0/src/codapact/targets/python/library.py +337 -0
  73. codapact-0.3.0/src/codapact/targets/python/naming.py +106 -0
  74. codapact-0.3.0/src/codapact/targets/typescript/__init__.py +1 -0
  75. codapact-0.3.0/src/codapact/targets/typescript/library.py +379 -0
  76. codapact-0.3.0/src/codapact/targets/typescript/runtime.ts +271 -0
  77. codapact-0.3.0/tests/fixtures/library_smoke.ts +11 -0
  78. codapact-0.3.0/tests/fixtures/outline_plugin.py +43 -0
  79. codapact-0.3.0/tests/fixtures/petstore_smoke.ts +15 -0
  80. codapact-0.3.0/tests/support.py +206 -0
  81. codapact-0.3.0/tests/test_architecture.py +89 -0
  82. codapact-0.3.0/tests/test_codec_serialize.py +155 -0
  83. codapact-0.3.0/tests/test_core.py +77 -0
  84. codapact-0.3.0/tests/test_generation.py +264 -0
  85. codapact-0.3.0/tests/test_model.py +152 -0
  86. codapact-0.3.0/tests/test_openapi_edges.py +180 -0
  87. codapact-0.3.0/tests/test_plugins_pipeline.py +245 -0
  88. codapact-0.3.0/tests/test_runtime.py +302 -0
  89. codapact-0.3.0/tests/test_runtime_edges.py +183 -0
  90. codapact-0.3.0/tests/test_shaping_surface_commands.py +227 -0
  91. codapact-0.3.0/tests/test_sources.py +317 -0
  92. {codapact-0.1.1 → codapact-0.3.0}/uv.lock +12 -341
  93. codapact-0.1.1/.github/workflows/mutation-alerts.yml +0 -73
  94. codapact-0.1.1/.github/workflows/mutation.yml +0 -55
  95. codapact-0.1.1/.release-please-manifest.json +0 -1
  96. codapact-0.1.1/PKG-INFO +0 -63
  97. codapact-0.1.1/README.md +0 -48
  98. codapact-0.1.1/docs/architecture.md +0 -82
  99. codapact-0.1.1/docs/configuration.md +0 -167
  100. codapact-0.1.1/docs/mutation.md +0 -106
  101. codapact-0.1.1/docs/releasing.md +0 -41
  102. codapact-0.1.1/docs/security.md +0 -35
  103. codapact-0.1.1/docs/support.md +0 -80
  104. codapact-0.1.1/docs/verification.md +0 -59
  105. codapact-0.1.1/examples/cli.json +0 -4
  106. codapact-0.1.1/examples/pets.codapact.yaml +0 -18
  107. codapact-0.1.1/examples/pets.yaml +0 -43
  108. codapact-0.1.1/examples/runtime.json +0 -5
  109. codapact-0.1.1/schemas/cli.v1.schema.json +0 -23
  110. codapact-0.1.1/scripts/mutation_alerts.py +0 -418
  111. codapact-0.1.1/scripts/mutation_report.py +0 -110
  112. codapact-0.1.1/src/codapact/__init__.py +0 -3
  113. codapact-0.1.1/src/codapact/__main__.py +0 -83
  114. codapact-0.1.1/src/codapact/auth.py +0 -68
  115. codapact-0.1.1/src/codapact/cli.py +0 -117
  116. codapact-0.1.1/src/codapact/configuration.py +0 -135
  117. codapact-0.1.1/src/codapact/errors.py +0 -30
  118. codapact-0.1.1/src/codapact/generation.py +0 -243
  119. codapact-0.1.1/src/codapact/loading.py +0 -135
  120. codapact-0.1.1/src/codapact/model.py +0 -88
  121. codapact-0.1.1/src/codapact/net.py +0 -106
  122. codapact-0.1.1/src/codapact/openapi.py +0 -294
  123. codapact-0.1.1/src/codapact/profiles.py +0 -175
  124. codapact-0.1.1/src/codapact/project.py +0 -182
  125. codapact-0.1.1/src/codapact/runtime.py +0 -197
  126. codapact-0.1.1/src/codapact/schemas/generation.v1.json +0 -57
  127. codapact-0.1.1/src/codapact/validation.py +0 -67
  128. codapact-0.1.1/src/codapact/values.py +0 -33
  129. codapact-0.1.1/tests/conftest.py +0 -176
  130. codapact-0.1.1/tests/test_adversarial.py +0 -140
  131. codapact-0.1.1/tests/test_configuration.py +0 -421
  132. codapact-0.1.1/tests/test_distribution.py +0 -104
  133. codapact-0.1.1/tests/test_entrypoint.py +0 -57
  134. codapact-0.1.1/tests/test_generated_contracts.py +0 -605
  135. codapact-0.1.1/tests/test_generation.py +0 -228
  136. codapact-0.1.1/tests/test_loading.py +0 -128
  137. codapact-0.1.1/tests/test_mutation_alerts.py +0 -363
  138. codapact-0.1.1/tests/test_mutation_contracts.py +0 -1217
  139. codapact-0.1.1/tests/test_net.py +0 -271
  140. codapact-0.1.1/tests/test_openapi.py +0 -84
  141. codapact-0.1.1/tests/test_reference_text_budget.py +0 -21
  142. codapact-0.1.1/tests/test_runtime.py +0 -230
  143. {codapact-0.1.1 → codapact-0.3.0}/.github/workflows/ci.yml +0 -0
  144. {codapact-0.1.1 → codapact-0.3.0}/.github/workflows/codeql.yml +0 -0
  145. {codapact-0.1.1 → codapact-0.3.0}/.github/workflows/release.yml +0 -0
  146. {codapact-0.1.1 → codapact-0.3.0}/LICENSE +0 -0
  147. {codapact-0.1.1 → codapact-0.3.0/docs}/branding/mark.svg +0 -0
  148. {codapact-0.1.1 → codapact-0.3.0/docs}/branding/wordmark.svg +0 -0
  149. {codapact-0.1.1 → codapact-0.3.0}/release-please-config.json +0 -0
  150. {codapact-0.1.1 → codapact-0.3.0}/scripts/verify_dist.py +0 -0
  151. {codapact-0.1.1 → codapact-0.3.0}/src/codapact/py.typed +0 -0
@@ -0,0 +1 @@
1
+ {".":"0.3.0"}
@@ -2,6 +2,32 @@
2
2
 
3
3
  <!-- markdownlint-configure-file { "MD024": { "siblings_only": true } } -->
4
4
 
5
+ ## [0.3.0](https://github.com/mikejhill/codapact/compare/v0.2.0...v0.3.0) (2026-11-10)
6
+
7
+
8
+ ### ⚠ BREAKING CHANGES
9
+
10
+ * the CLI, configuration format, and generated code are new.
11
+
12
+ ### Features
13
+
14
+ * 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))
15
+
16
+ ## [0.2.0](https://github.com/mikejhill/codapact/compare/v0.1.1...v0.2.0) (2026-10-29)
17
+
18
+ ### Features
19
+
20
+ * Generate the same specialized endpoint subset for typed clients and CLI wrappers, using
21
+ operation IDs, method names, path globs, and domain tags with explicit include/exclude rules.
22
+ * Add versioned generation settings, CLI overrides, an owned selection report, and dry-run
23
+ generation/ownership preflight without output writes.
24
+ * Preserve selected nested schema dependencies and authentication requirements, stable CLI
25
+ renames, deterministic regeneration, and unrelated user files.
26
+ * Provide a GET/HEAD/OPTIONS read preset and runnable domain profiles. Method selection is
27
+ not a safety guarantee or server authorization control.
28
+
29
+ Implemented in [PR #16](https://github.com/mikejhill/codapact/pull/16).
30
+
5
31
  ## [0.1.1](https://github.com/mikejhill/codapact/compare/v0.1.0...v0.1.1) (2026-10-29)
6
32
 
7
33
  ### Bug Fixes
@@ -0,0 +1,87 @@
1
+ Metadata-Version: 2.4
2
+ Name: codapact
3
+ Version: 0.3.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
+ ![CodaPact wordmark](docs/branding/wordmark.svg)
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; JSON/YAML/raw output; 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)
@@ -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
+ ![CodaPact wordmark](docs/branding/wordmark.svg)
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; JSON/YAML/raw output; 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,146 @@
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/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
+ | Protocol | `ProtocolAdapter.supports/call` | `RuntimeClient(adapters=…)` |
91
+
92
+ ### Plugin protocol
93
+
94
+ - `describe` prints `{"name", "capabilities", "needs_commands"}`.
95
+ - `generate` reads a `GenerationRequest` (`protocol_version`, model, surface, optional
96
+ command tree, options) and prints a `GenerationResponse` (files + diagnostics).
97
+ - File paths are validated (relative, no `..`, no absolute or drive paths) before writing.
98
+ - Any language can implement a plugin; it never imports CodaPact internals.
99
+
100
+ ### Capability negotiation
101
+
102
+ `required_capabilities(api)` yields tokens such as `binding:http`, `binding:graphql`,
103
+ `auth:bearer`, `pagination:cursor`, `type:union`, `type:map`, `type:literal`. A target
104
+ missing any token fails before generation with `CapabilityError`, rather than emitting code
105
+ that silently mishandles the feature.
106
+
107
+ ## Runtime
108
+
109
+ - `RuntimeClient(api, base_url, auth, transport, middleware, adapters, …)`:
110
+ `call(operation, args)` encodes and validates arguments, picks the adapter for the
111
+ operation's binding, and decodes the result. `paginate()` follows cursors or offsets.
112
+ - `SafeHttpClient` (default transport): no redirects, bounded bodies, DNS pinned against
113
+ rebinding, private and plaintext addresses only with explicit opt-in.
114
+ - `Retry` middleware: idempotent operations only, exponential backoff, honors
115
+ `Retry-After`.
116
+ - Auth: `StaticAuth`, `EnvAuth` (`<PREFIX>_<SCHEME>`), `ChainAuth`. `Credential.__repr__`
117
+ never renders secrets.
118
+ - Errors: `ValidationError`, `AuthError`, `ApiError` (status, named error case, decoded
119
+ payload), `GraphQLResponseError`, `TransportError`.
120
+
121
+ ## Lessons from existing tools
122
+
123
+ | Tool | What it does well | What CodaPact takes |
124
+ | --- | --- | --- |
125
+ | Smithy | Protocol-agnostic model; traits; projections | Semantics separate from bindings; shaping as projections over one model |
126
+ | Fern | Versioned IR consumed by generators | Serialized, versioned model with migrations; generators read IR, not contracts |
127
+ | Kiota | Abstractions package separate from HTTP implementation | Runtime seams (`Transport`, `AuthProvider`, `Middleware`) with swappable defaults |
128
+ | protoc | Plugins as executables over a request/response protocol | Out-of-process targets with a `describe`/`generate` handshake |
129
+ | Stainless | Config-driven resource grouping and naming; hand-edit safety | `group`/`rename` transforms; ownership manifest guards hand-written files |
130
+ | Speakeasy | Overlays; retries and pagination declared in config | `paginate` transform; idempotent-only retries with `Retry-After` |
131
+ | graphql-codegen | Exact result types per operation document | Selection-specific result types; `__typename`-discriminated unions |
132
+ | restish | Generic CLI from a contract at runtime | CLI is a thin layer over the same runtime the library uses |
133
+
134
+ Deliberate differences:
135
+
136
+ - One model for REST and GraphQL instead of one generator per protocol.
137
+ - CLI derived from the library surface, so the two cannot drift.
138
+ - Capability checks instead of best-effort output for unsupported features.
139
+
140
+ ## Testing strategy
141
+
142
+ - Each layer has unit tests against hand-built inputs from the layer below.
143
+ - `tests/support.py` provides in-memory petstore (REST) and library (GraphQL) servers and a
144
+ `FakeTransport`; generated clients are also exercised over real loopback HTTP.
145
+ - Generated Python is type checked with `ty`; generated TypeScript runs under Node.
146
+ - The external plugin fixture uses only the public protocol helpers.
@@ -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](../branding/wordmark.svg) on light backgrounds and
20
- [the standalone mark](../branding/mark.svg) where space is limited. SVGs use
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
@@ -0,0 +1,91 @@
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: {program: petstore}
26
+ targets:
27
+ - {name: python, output: out/python, options: {package: petstore}}
28
+ - {name: python-cli, output: out/python}
29
+ - {name: typescript, output: out/ts, options: {package: petstore}}
30
+ - {plugin: [python, my_plugin.py], output: out/custom}
31
+ ```
32
+
33
+ Targets that share an `output` directory share options. When `python-cli` shares the
34
+ `python` directory, the library's `pyproject.toml` gains the CLI script entry.
35
+
36
+ ## Sources
37
+
38
+ | Source | Option | Default | Meaning |
39
+ | --- | --- | --- | --- |
40
+ | both | `strict` | `true` | Unsupported features are errors; when `false`, they degrade with a warning |
41
+ | `graphql` | `name` | `GraphQL API` | API name |
42
+ | `graphql` | `version` | empty | API version |
43
+ | `graphql` | `url` | none | Endpoint; becomes the default server |
44
+ | `graphql` | `auth` | none | `bearer`, `basic`, or `{api_key: HEADER}`; required on every operation |
45
+ | `graphql` | `depth` | `1` | Object nesting synthesized in schema mode (0–8) |
46
+
47
+ GraphQL with `documents` generates one operation per document operation with exact result
48
+ types. Without documents, it generates one operation per root field.
49
+
50
+ ## Shaping transforms
51
+
52
+ | Transform | Config |
53
+ | --- | --- |
54
+ | `select` | `include`, `exclude`: lists of globs or `{name, tag, kind, namespace, read_only}` selectors |
55
+ | `rename` | `operations`, `types`, `fields` (`Type.field`), `params` (`op.param`); wire names are kept |
56
+ | `group` | `by: tag` or `by: path`, and/or `operations: {glob: dotted.namespace}` |
57
+ | `paginate` | `operations`, `style: cursor` (`param`, `next`) or `offset` (`param`, `limit_param`), `items` |
58
+ | `prune` | none; removes unreachable types (also run by `select`) |
59
+
60
+ ## Surface options
61
+
62
+ | Option | Default | Meaning |
63
+ | --- | --- | --- |
64
+ | `flatten_body` | `true` | Expose record body fields as individual method params |
65
+ | `trim_namespace` | `true` | `pets.list_pets` becomes `pets.list` unless that collides |
66
+
67
+ ## Targets
68
+
69
+ | Target | Option | Default |
70
+ | --- | --- | --- |
71
+ | `python` | `package` | from API name |
72
+ | `python` | `distribution` | package with `-` |
73
+ | `python` | `version` | `0.1.0` |
74
+ | `typescript` | `package` | API name in kebab case |
75
+ | `typescript` | `version` | `0.1.0` |
76
+
77
+ ## Generated CLI settings
78
+
79
+ Precedence: flag, then environment, then settings file.
80
+
81
+ | Setting | Flag | Environment | File key |
82
+ | --- | --- | --- | --- |
83
+ | Base URL | `--base-url` | `<PREFIX>_BASE_URL` | `base_url` |
84
+ | Timeout | `--timeout` | `<PREFIX>_TIMEOUT` | `timeout` |
85
+ | Private network | none | `<PREFIX>_ALLOW_PRIVATE` | `allow_private` |
86
+ | Credentials | none | `<PREFIX>_<SCHEME>`; basic uses `_USERNAME`/`_PASSWORD` | not stored |
87
+
88
+ The settings file is `--config PATH` or `$XDG_CONFIG_HOME/<program>/config.json`.
89
+ `<PREFIX>` is the program name in upper snake case.
90
+
91
+ Exit codes: `0` success, `1` API error, `2` usage or validation, `3` auth, `4` transport.
@@ -0,0 +1,20 @@
1
+ version: 1
2
+ source:
3
+ type: graphql
4
+ path: schema.graphql
5
+ documents: [operations.graphql]
6
+ options:
7
+ name: Library
8
+ url: https://library.example.com/graphql
9
+ auth: bearer
10
+ cli:
11
+ program: library
12
+ targets:
13
+ - name: python
14
+ output: generated/python
15
+ options: {package: library}
16
+ - name: python-cli
17
+ output: generated/python
18
+ - name: typescript
19
+ output: generated/typescript
20
+ options: {package: library}
@@ -0,0 +1,13 @@
1
+ query BookTitles($genre: Genre) {
2
+ books(genre: $genre) { ...BookSummary }
3
+ }
4
+
5
+ query Dashboard {
6
+ featured: book(id: "1") { title author { name } }
7
+ results: search(text: "a") {
8
+ ... on Book { title }
9
+ ... on Author { name }
10
+ }
11
+ }
12
+
13
+ fragment BookSummary on Book { id title genre }
@@ -0,0 +1,49 @@
1
+ """A small library catalogue used by Codapact examples and tests."""
2
+ schema { query: Query mutation: Mutation }
3
+
4
+ scalar DateTime
5
+
6
+ enum Genre { FICTION NON_FICTION POETRY }
7
+
8
+ interface Node { id: ID! }
9
+
10
+ type Author implements Node {
11
+ id: ID!
12
+ name: String!
13
+ books: [Book!]!
14
+ }
15
+
16
+ type Book implements Node {
17
+ id: ID!
18
+ title: String!
19
+ genre: Genre!
20
+ publishedAt: DateTime
21
+ author: Author!
22
+ }
23
+
24
+ type Magazine implements Node {
25
+ id: ID!
26
+ title: String!
27
+ issue: Int!
28
+ }
29
+
30
+ union SearchResult = Book | Author | Magazine
31
+
32
+ input NewBook {
33
+ title: String!
34
+ genre: Genre!
35
+ authorId: ID!
36
+ }
37
+
38
+ type Query {
39
+ "Fetch one book by id."
40
+ book(id: ID!): Book
41
+ books(genre: Genre, first: Int = 10): [Book!]!
42
+ search(text: String!): [SearchResult!]!
43
+ node(id: ID!): Node
44
+ }
45
+
46
+ type Mutation {
47
+ "Add a book to the catalogue."
48
+ addBook(input: NewBook!): Book!
49
+ }
@@ -0,0 +1,23 @@
1
+ version: 1
2
+ source:
3
+ type: openapi
4
+ path: openapi.yaml
5
+ shape:
6
+ - group: {by: tag}
7
+ - paginate:
8
+ operations: [list_pets]
9
+ style: cursor
10
+ param: cursor
11
+ next: next_cursor
12
+ items: items
13
+ cli:
14
+ program: petstore
15
+ targets:
16
+ - name: python
17
+ output: generated/python
18
+ options: {package: petstore}
19
+ - name: python-cli
20
+ output: generated/python
21
+ - name: typescript
22
+ output: generated/typescript
23
+ options: {package: petstore}