Pure-julia OpenAPI internals rewrite

.github/workflows/CI.yml

@@ -0,0 +1,40 @@
+name: CI
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version: ['1.11', '1']
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+  corpus:
+    name: OpenAPI corpus
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      OPENAPI_CORPUS_TESTS: ${{ startsWith(github.ref, 'refs/tags/') && 'all' || 'small' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1

.github/workflows/TagBot.yml

@@ -8,8 +8,20 @@ jobs:
   TagBot:
     if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
     runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      checks: read
+      contents: write
+      deployments: read
+      issues: read
+      discussions: read
+      packages: read
+      pages: read
+      pull-requests: read
+      repository-projects: read
+      security-events: read
+      statuses: read
     steps:
       - uses: JuliaRegistries/TagBot@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          ssh: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -1,2 +1,7 @@
-Manifest.toml
-.vscode
+*.jl.cov
+*.jl.*.cov
+*.jl.mem
+.DS_Store
+/Manifest.toml
+/Manifest-v*.toml
+/test/Manifest.toml

AGENTS.md

@@ -0,0 +1,149 @@
+# OpenAPI.jl maintainer guide
+
+## Purpose
+
+OpenAPI.jl has three related surfaces:
+
+1. It reads OpenAPI 3.0, 3.1, and 3.2 descriptions and generates typed Julia
+   clients.
+2. It generates typed Julia server-stub modules from the same descriptions;
+   the framework router glue comes from extensions (`OpenAPIHTTPExt` for
+   `HTTP.Router`, downstream packages such as Servo.jl for their own routers)
+   through the `server_source` seam.
+3. It creates a smaller OpenAPI 3.2 document from declared Julia operations.
+
+The generators must fail before code emission when they cannot preserve the
+specified wire behavior. Do not generate a plausible but incorrect client or
+server.
+
+## Architecture
+
+The client pipeline has strict stage boundaries:
+
+```text
+source
+  -> load and structural validation
+  -> reference resolution and normalization
+  -> typed client planning
+  -> deterministic Julia source generation
+  -> generated runtime validation and HTTP transport
+```
+
+The main files are:
+
+- `src/loading.jl`: JSON/YAML parsing, official OAS schema checks, source
+  identity, limits, and source locations.
+- `src/schema_engine/`: provisional generic JSON Schema resources, references,
+  dialects, compilation, rebasing, and validation. Keep this directory free of
+  OpenAPI-specific behavior so it can move upstream later.
+- `src/references.jl`: bounded OpenAPI object reference resolution and the
+  adapter to the internal schema engine.
+- `src/normalize.jl`: immutable, version-neutral OpenAPI intermediate forms and
+  semantic checks.
+- `src/planning.jl`: Julia names, model shapes, operation signatures, and
+  explicit generation support checks.
+- `src/client.jl`: source emission and the runtime embedded in generated
+  clients.
+- `src/schemas.jl`, `src/document.jl`: Julia type schema mapping and the smaller
+  document-authoring API.
+- `ext/OpenAPIHTTPExt.jl`: HTTP document retrieval.
+
+## Design rules
+
+- Keep the package export surface empty. Users call `OpenAPI.load`,
+  `OpenAPI.normalize`, `OpenAPI.plan`, and `OpenAPI.client` through the module.
+- Keep parsed and normalized documents immutable. Do not mutate caller-owned
+  input.
+- Keep diagnostics stable and machine-readable. Include a resource and JSON
+  Pointer location.
+- Keep network and file reference access bounded. Preserve same-origin and
+  explicit-root defaults.
+- Keep generic URI, resource, pointer, reference, dialect, compilation, and
+  validation behavior in `src/schema_engine`. Add OpenAPI-specific rules only
+  outside that directory.
+- Treat `src/schema_engine` as provisional. Preserve its extraction boundary
+  so the code can move to JSONSchema.jl after it hardens.
+- Do not add a dependency on Servo or another server framework. Downstream
+  packages own their router integration through package extensions built on
+  the `server_source`, `register!`, and `operations` seams; only HTTP.jl glue
+  lives in this repository (in `OpenAPIHTTPExt`).
+- Put generic strict JSON parsing behavior in JSON.jl when it belongs there.
+- Treat the normative OpenAPI text as authoritative over published structural
+  schemas.
+- Preserve distinct missing, explicit-null, request, and response model
+  semantics.
+- Keep generation deterministic. Sort unordered document maps before they
+  affect names or emitted source.
+- Do not silently approximate unsupported wire behavior. The known deliberate
+  planning failures are OAS 3.2 `querystring` parameters and streaming or
+  positional `itemSchema`, `itemEncoding`, and `prefixEncoding` behavior; the
+  server planner additionally rejects non-form-data `multipart/*` request
+  bodies and operations with more than one exploded object query or cookie
+  parameter.
+
+## Public types and functions
+
+- `SourceDocument`, `Diagnostic`, `OpenAPIError`: loading and diagnostics.
+- `NormalizedAPI`: immutable normalized document.
+- `ClientPlan`, `ServerPlan`: deterministic generation plans.
+- `load`, `check`, `normalize`, `plan`, `client`: client pipeline.
+- `serverplan`, `server`, `server_module_source`: server-stub generation.
+- `Param`, `Operation`, `document`: declaration-based authoring API.
+- `register!`, `operations`, `server_source`: extension seams implemented by
+  the HTTP extension and downstream server packages.
+
+Generated modules have their own public runtime types. Important types include
+`Client`, credential types, `Upload`, `MultipartPartHeaders`, `ApiResponse`,
+`ApiError`, `SchemaValidationError`, `Absent`, and `ABSENT`.
+
+## Tests
+
+Run the package tests on both supported Julia minor lines:
+
+```sh
+julia +1.12 --project=. -e 'using Pkg; Pkg.test()'
+julia +1.11 --project=. -e 'using Pkg; Pkg.test()'
+```
+
+The focused files separate concerns:
+
+- `test/normalization.jl`: loading, versions, immutability, generated source.
+- `test/references.jl`: external, anchor, recursive, and cyclic references.
+- `test/semantics.jl`: OpenAPI semantic rules and explicit deferrals.
+- `test/models.jl`, `test/discriminators.jl`: schema-to-type edge cases.
+- `test/runtime.jl`: generated runtime units.
+- `test/runtime_integration.jl`: live local HTTP behavior.
+- `test/schema_engine/`: direct resource, compilation, validation, and rebasing
+  coverage for the provisional schema engine.
+- `test/corpus.jl`: pinned public API descriptions.
+
+Run corpus checks separately:
+
+```sh
+OPENAPI_CORPUS_TESTS=small julia --project=. -e 'using Pkg; Pkg.test()'
+OPENAPI_CORPUS_TESTS=all julia --project=. -e 'using Pkg; Pkg.test()'
+```
+
+When a test changes expected wire bytes, inspect the bytes or HTTP request. A
+source-compilation check alone is not enough.
+
+## Dependency development
+
+OpenAPI.jl requires JSON.jl 1.7. The additional schema engine is currently
+internal. Changes to it need direct tests and full OpenAPI corpus validation.
+Do not couple its internals to OpenAPI normalization or planning.
+
+## Common change workflow
+
+1. Add or pin a specification example that demonstrates the behavior.
+2. Add a normalized semantic test before changing generated source.
+3. Add runtime or live HTTP coverage when bytes, headers, security, or response
+   selection change.
+4. Run focused tests.
+5. Run the full Julia 1.12 and 1.11 suites.
+6. Run the small corpus. Run the full corpus for reference, planning, naming,
+   schema, or generation changes.
+7. Check `git diff --check` and inspect generated source for deterministic
+   output.
+
+Do not push or publish without direct user approval.

LICENSE.md

@@ -1,22 +1,22 @@
 The OpenAPI.jl package is licensed under the MIT "Expat" License:
 
-Copyright (c) 2022: Julia Computing Inc. All rights reserved.
- 
-> Permission is hereby granted, free of charge, to any person obtaining a copy
-> of this software and associated documentation files (the "Software"), to deal
-> in the Software without restriction, including without limitation the rights
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-> copies of the Software, and to permit persons to whom the Software is
-> furnished to do so, subject to the following conditions:
-> 
-> The above copyright notice and this permission notice shall be included in all
-> copies or substantial portions of the Software.
-> 
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-> SOFTWARE.
-> 
+> Copyright (c) 2026: Jacob Quinn, JuliaServices contributors.
+>
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> "Software"), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+>
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.