@workos/oagen 0.22.7 → 0.23.0
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.
- package/README.md +1 -1
- package/dist/cli/index.mjs +142 -33
- package/dist/cli/index.mjs.map +1 -1
- package/dist/compat/index.d.mts +2 -2
- package/dist/compat/index.mjs +7 -7
- package/dist/compat/index.mjs.map +1 -1
- package/dist/{diff-D4XaiPeA.mjs → diff-B7dMUCoJ.mjs} +128 -19
- package/dist/diff-B7dMUCoJ.mjs.map +1 -0
- package/dist/{differ-Q13KY9Rd.d.mts → differ-DMmw0tbA.d.mts} +5 -5
- package/dist/{differ-Q13KY9Rd.d.mts.map → differ-DMmw0tbA.d.mts.map} +1 -1
- package/dist/index.d.mts +50 -9
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +9 -11
- package/dist/index.mjs.map +1 -1
- package/dist/{overlay-cb32jDBS.mjs → overlay-sQHQoN0I.mjs} +4 -4
- package/dist/overlay-sQHQoN0I.mjs.map +1 -0
- package/dist/scripts/smoke/baseline.mjs +8 -10
- package/dist/scripts/smoke/baseline.mjs.map +1 -1
- package/dist/scripts/smoke/sdk-test.mjs +3 -3
- package/dist/scripts/smoke/sdk-test.mjs.map +1 -1
- package/dist/smoke.d.mts +3 -4
- package/dist/smoke.d.mts.map +1 -1
- package/dist/smoke.mjs +8 -10
- package/dist/smoke.mjs.map +1 -1
- package/dist/{types-DZrKFHis.d.mts → types-nM5Kp7UP.d.mts} +7 -9
- package/dist/types-nM5Kp7UP.d.mts.map +1 -0
- package/dist/verify/index.d.mts +2 -2
- package/dist/verify/index.mjs +2 -2
- package/docs/architecture/extractor-contract.md +2 -2
- package/docs/architecture/pipeline.md +2 -2
- package/docs/cli.md +19 -19
- package/docs/core/compatibility-policy.md +1 -1
- package/docs/core/manifest-schema.md +2 -2
- package/package.json +1 -1
- package/skills/generate-emitter/SKILL.md +2 -2
- package/skills/generate-emitter/references/common-pitfalls.md +1 -1
- package/skills/generate-emitter/references/project-scaffold.md +3 -3
- package/skills/generate-extractor/SKILL.md +2 -2
- package/skills/generate-smoke-test/SKILL.md +1 -1
- package/skills/verify-smoke-test/SKILL.md +1 -1
- package/dist/diff-D4XaiPeA.mjs.map +0 -1
- package/dist/overlay-cb32jDBS.mjs.map +0 -1
- package/dist/types-DZrKFHis.d.mts.map +0 -1
|
@@ -290,7 +290,7 @@ type CompatProvenance = 'spec_shape_change' | 'spec_ordering_change' | 'emitter_
|
|
|
290
290
|
type CompatFailLevel = 'none' | 'breaking' | 'soft-risk';
|
|
291
291
|
/** A single intentional-break approval in `oagen.config.ts`. */
|
|
292
292
|
interface CompatApproval {
|
|
293
|
-
/** Fully-qualified symbol (e.g., "
|
|
293
|
+
/** Fully-qualified symbol (e.g., "Acme\\Service\\Users::createUser"). */
|
|
294
294
|
symbol: string;
|
|
295
295
|
/** The kind of change being approved. */
|
|
296
296
|
category: CompatChangeCategory;
|
|
@@ -380,8 +380,7 @@ interface ErrorPolicy {
|
|
|
380
380
|
serverErrorKind: string;
|
|
381
381
|
/** Catch-all error kind for unrecognized status codes. */
|
|
382
382
|
clientErrorKind: string;
|
|
383
|
-
/** URL template for error documentation. Use {code} as placeholder for the API error code.
|
|
384
|
-
* Example: 'https://workos.com/docs/errors/{code}' */
|
|
383
|
+
/** URL template for error documentation. Use {code} as placeholder for the API error code. */
|
|
385
384
|
errorDocUrlTemplate?: string;
|
|
386
385
|
}
|
|
387
386
|
/** Telemetry — what request metrics to track and send. */
|
|
@@ -419,7 +418,7 @@ interface UserAgentPolicy {
|
|
|
419
418
|
/** Template for the SDK identifier string.
|
|
420
419
|
* Placeholders: {name} = spec name, {lang} = emitter language, {version} = SDK version.
|
|
421
420
|
* Each emitter interpolates with its own language string and casing conventions.
|
|
422
|
-
* Example: '{name} {lang}/{version}' → '
|
|
421
|
+
* Example: '{name} {lang}/{version}' → 'Acme PHP/4.32.0' */
|
|
423
422
|
sdkIdentifierTemplate: string;
|
|
424
423
|
/** Whether to append the runtime/language version (e.g. PHP 8.2, Python 3.12). */
|
|
425
424
|
includeRuntimeVersion: boolean;
|
|
@@ -445,7 +444,7 @@ interface RequestGuardPolicy {
|
|
|
445
444
|
interface TimeoutPolicy {
|
|
446
445
|
/** Default HTTP request timeout in seconds. */
|
|
447
446
|
defaultTimeoutSeconds: number;
|
|
448
|
-
/** Environment variable name to override the timeout (e.g. '
|
|
447
|
+
/** Environment variable name to override the timeout (e.g. 'SDK_REQUEST_TIMEOUT'). */
|
|
449
448
|
timeoutEnvVar?: string;
|
|
450
449
|
}
|
|
451
450
|
/** Language-agnostic runtime policies for generated SDKs.
|
|
@@ -462,9 +461,8 @@ interface SdkBehavior {
|
|
|
462
461
|
timeout: TimeoutPolicy;
|
|
463
462
|
}
|
|
464
463
|
/**
|
|
465
|
-
* Canonical SDK behavior defaults.
|
|
466
|
-
*
|
|
467
|
-
* via `mergeSdkBehavior()` in each SDK's `oagen.config.ts`.
|
|
464
|
+
* Canonical SDK behavior defaults. Per-language or per-project overrides can
|
|
465
|
+
* be applied via `mergeSdkBehavior()` in each SDK's `oagen.config.ts`.
|
|
468
466
|
*
|
|
469
467
|
* - Retry: exponential backoff with jitter, retries on 429/5xx
|
|
470
468
|
* - Errors: standard HTTP status → exception kind mapping
|
|
@@ -793,4 +791,4 @@ interface SuccessResponse {
|
|
|
793
791
|
}
|
|
794
792
|
//#endregion
|
|
795
793
|
export { BreakingChangeCategory as $, collectEnumRefs as A, CompatSourceKind as At, IdempotencyPolicy as B, CompatPolicyHints as Bt, Service as C, OverlayLookup as Ct, UnionType as D, CompatParameter as Dt, TypeRef as E, ViolationSeverity as Et, walkTypeRef as F, CompatVisibility as Ft, RetryPolicy as G, LoggingPolicy as H, mergePolicy as Ht, AiAgentEnvVar as I, LanguageId as It, TimeoutPolicy as J, SdkBehavior as K, BackoffStrategy as L, ParameterSensitivity as Lt, collectModelRefs as M, CompatSymbol as Mt, collectRequestBodyModels as N, CompatSymbolKind as Nt, assertNever as O, CompatPassingStyle as Ot, mapTypeRef as P, CompatTypeRef as Pt, AdditiveChangeCategory as Q, DeepPartial as R, apiSurfaceToSnapshot as Rt, ServerEntry as S, MethodOverlay as St, TypeParam as T, ViolationCategory as Tt, PaginationPolicy as U, LogEvent as V, getDefaultPolicy as Vt, RequestGuardPolicy as W, defaultSdkBehavior as X, UserAgentPolicy as Y, mergeSdkBehavior as Z, Parameter as _, ApiSurface as _t, EnumRef as a, CompatProvenance as at, PrimitiveType as b, Extractor as bt, Field as c, severityMeetsThreshold as ct, MapType as d, ApiEnum as dt, CompatApproval as et, Model as f, ApiField as ft, PaginationMeta as g, ApiProperty as gt, Operation as h, ApiParam as ht, Enum as i, CompatFailLevel as it, collectFieldDependencies as j, CompatStability as jt, assignModelsToServices as k, CompatSnapshot as kt, HttpMethod as l, Addition as lt, NullableType as m, ApiMethod as mt, ArrayType as n, CompatChangeSeverity as nt, EnumValue as o, SoftRiskChangeCategory as ot, ModelRef as p, ApiInterface as pt, TelemetryPolicy as q, AuthScheme as r, CompatConfig as rt, ErrorResponse as s, defaultSeverityForCategory as st, ApiSpec as t, CompatChangeCategory as tt, LiteralType as u, ApiClass as ut, ParameterGroup as v, ApiTypeAlias as vt, SuccessResponse as w, Violation as wt, SecurityRequirement as x, LanguageHints as xt, ParameterGroupVariant as y, DiffResult as yt, ErrorPolicy as z, ALL_LANGUAGE_IDS as zt };
|
|
796
|
-
//# sourceMappingURL=types-
|
|
794
|
+
//# sourceMappingURL=types-nM5Kp7UP.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types-nM5Kp7UP.d.mts","names":[],"sources":["../src/compat/policy.ts","../src/compat/ir.ts","../src/compat/types.ts","../src/compat/config.ts","../src/ir/sdk-behavior.ts","../src/ir/types.ts"],"mappings":"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"}
|
package/dist/verify/index.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { Bt as CompatPolicyHints, _t as ApiSurface, t as ApiSpec, wt as Violation } from "../types-
|
|
2
|
-
import { t as CompatDiffResult } from "../differ-
|
|
1
|
+
import { Bt as CompatPolicyHints, _t as ApiSurface, t as ApiSpec, wt as Violation } from "../types-nM5Kp7UP.mjs";
|
|
2
|
+
import { t as CompatDiffResult } from "../differ-DMmw0tbA.mjs";
|
|
3
3
|
|
|
4
4
|
//#region src/verify/types.d.ts
|
|
5
5
|
interface VerifyDiagnostics {
|
package/dist/verify/index.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { m as CommandError } from "../tree-sitter-DcUvm0KA.mjs";
|
|
2
|
-
import { a as MANIFEST_FILENAME, i as generate, n as getEmitter, t as diffSpecs } from "../diff-
|
|
3
|
-
import { A as getDefaultPolicy, T as apiSurfaceToSnapshot, c as filterSurface, f as specDerivedMethodPaths, i as getExtractor, j as mergePolicy, l as specDerivedEnumValues, n as isPatchableChange, o as diffSnapshots, p as specDerivedNames, r as patchOverlay, t as buildOverlayLookup, u as specDerivedFieldPaths } from "../overlay-
|
|
2
|
+
import { a as MANIFEST_FILENAME, i as generate, n as getEmitter, t as diffSpecs } from "../diff-B7dMUCoJ.mjs";
|
|
3
|
+
import { A as getDefaultPolicy, T as apiSurfaceToSnapshot, c as filterSurface, f as specDerivedMethodPaths, i as getExtractor, j as mergePolicy, l as specDerivedEnumValues, n as isPatchableChange, o as diffSnapshots, p as specDerivedNames, r as patchOverlay, t as buildOverlayLookup, u as specDerivedFieldPaths } from "../overlay-sQHQoN0I.mjs";
|
|
4
4
|
import * as path$1 from "node:path";
|
|
5
5
|
import { fileURLToPath } from "node:url";
|
|
6
6
|
import { execFileSync } from "node:child_process";
|
|
@@ -99,11 +99,11 @@ Extractors are registered via `oagen.config.ts` in the consumer project. The CLI
|
|
|
99
99
|
|
|
100
100
|
```typescript
|
|
101
101
|
// oagen.config.ts (consumer project)
|
|
102
|
-
import {
|
|
102
|
+
import { acmeEmittersPlugin } from "@acme/oagen-emitters";
|
|
103
103
|
import type { OagenConfig } from "@workos/oagen";
|
|
104
104
|
|
|
105
105
|
const config: OagenConfig = {
|
|
106
|
-
...
|
|
106
|
+
...acmeEmittersPlugin, // includes all extractors
|
|
107
107
|
// spec interpretation policy...
|
|
108
108
|
};
|
|
109
109
|
export default config;
|
|
@@ -97,10 +97,10 @@ Simple map from language name → `Emitter` instance. Emitters are registered at
|
|
|
97
97
|
|
|
98
98
|
```typescript
|
|
99
99
|
// In oagen.config.ts (consumer project)
|
|
100
|
-
import {
|
|
100
|
+
import { acmeEmittersPlugin } from "@acme/oagen-emitters";
|
|
101
101
|
|
|
102
102
|
export default {
|
|
103
|
-
...
|
|
103
|
+
...acmeEmittersPlugin,
|
|
104
104
|
// spec interpretation policy...
|
|
105
105
|
};
|
|
106
106
|
```
|
package/docs/cli.md
CHANGED
|
@@ -7,19 +7,19 @@ All commands support `--help` for full usage details.
|
|
|
7
7
|
Generate SDK code from an OpenAPI spec.
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
oagen generate --spec openapi.yml --lang node --output ./sdk --namespace
|
|
10
|
+
oagen generate --spec openapi.yml --lang node --output ./sdk --namespace Acme
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
| Argument | Required | Default | Description
|
|
14
|
-
| ---------------------- | -------- | ----------------------- |
|
|
15
|
-
| `--spec <path>` | No | `OPENAPI_SPEC_PATH` env | Path to an OpenAPI 3.x spec file.
|
|
16
|
-
| `--lang <language>` | Yes | | Target language — must have a registered emitter (via `oagen.config.ts`)
|
|
17
|
-
| `--output <dir>` | Yes | | Directory to write generated files into
|
|
18
|
-
| `--namespace <name>` | No | Spec's `info.title` | SDK namespace in PascalCase — used directly for code identifiers (e.g., `
|
|
19
|
-
| `--dry-run` | No | `false` | Print the list of file paths that would be generated, without writing anything to disk
|
|
20
|
-
| `--api-surface <path>` | No | | Path to baseline API surface JSON for compat overlay
|
|
21
|
-
| `--target <dir>` | No | | Target directory for live SDK integration — generated files are merged into this directory instead of `--output`
|
|
22
|
-
| `--no-compat-check` | No | `false` | Skip compat overlay even if `--api-surface` is provided
|
|
13
|
+
| Argument | Required | Default | Description |
|
|
14
|
+
| ---------------------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| `--spec <path>` | No | `OPENAPI_SPEC_PATH` env | Path to an OpenAPI 3.x spec file. |
|
|
16
|
+
| `--lang <language>` | Yes | | Target language — must have a registered emitter (via `oagen.config.ts`) |
|
|
17
|
+
| `--output <dir>` | Yes | | Directory to write generated files into |
|
|
18
|
+
| `--namespace <name>` | No | Spec's `info.title` | SDK namespace in PascalCase — used directly for code identifiers (e.g., `Acme::Client`) and converted to `snake_case` for file paths (e.g., `lib/acme/`). Use PascalCase with the exact casing you want. |
|
|
19
|
+
| `--dry-run` | No | `false` | Print the list of file paths that would be generated, without writing anything to disk |
|
|
20
|
+
| `--api-surface <path>` | No | | Path to baseline API surface JSON for compat overlay |
|
|
21
|
+
| `--target <dir>` | No | | Target directory for live SDK integration — generated files are merged into this directory instead of `--output` |
|
|
22
|
+
| `--no-compat-check` | No | `false` | Skip compat overlay even if `--api-surface` is provided |
|
|
23
23
|
|
|
24
24
|
## `oagen diff`
|
|
25
25
|
|
|
@@ -244,11 +244,11 @@ The config file belongs to the **consumer project** (the project that owns spec
|
|
|
244
244
|
|
|
245
245
|
```ts
|
|
246
246
|
import type { OagenConfig } from "@workos/oagen";
|
|
247
|
-
import {
|
|
247
|
+
import { acmeEmittersPlugin } from "@acme/oagen-emitters";
|
|
248
248
|
|
|
249
249
|
const config: OagenConfig = {
|
|
250
|
-
...
|
|
251
|
-
docUrl: "https://
|
|
250
|
+
...acmeEmittersPlugin,
|
|
251
|
+
docUrl: "https://docs.example.com",
|
|
252
252
|
operationIdTransform: (id) => id.replace(/Controller_/, ""),
|
|
253
253
|
operationHints,
|
|
254
254
|
mountRules,
|
|
@@ -276,20 +276,20 @@ export default config;
|
|
|
276
276
|
|
|
277
277
|
```ts
|
|
278
278
|
import type { OagenConfig } from "@workos/oagen";
|
|
279
|
-
import {
|
|
279
|
+
import { acmeEmittersPlugin } from "@acme/oagen-emitters";
|
|
280
280
|
import { experimentalPlugin } from "@workos/oagen-experimental";
|
|
281
281
|
|
|
282
282
|
const config: OagenConfig = {
|
|
283
283
|
emitters: [
|
|
284
|
-
...(
|
|
284
|
+
...(acmeEmittersPlugin.emitters ?? []),
|
|
285
285
|
...(experimentalPlugin.emitters ?? []),
|
|
286
286
|
],
|
|
287
287
|
extractors: [
|
|
288
|
-
...(
|
|
288
|
+
...(acmeEmittersPlugin.extractors ?? []),
|
|
289
289
|
...(experimentalPlugin.extractors ?? []),
|
|
290
290
|
],
|
|
291
291
|
smokeRunners: {
|
|
292
|
-
...(
|
|
292
|
+
...(acmeEmittersPlugin.smokeRunners ?? {}),
|
|
293
293
|
...(experimentalPlugin.smokeRunners ?? {}),
|
|
294
294
|
},
|
|
295
295
|
operationHints,
|
|
@@ -310,7 +310,7 @@ export default config;
|
|
|
310
310
|
| `operationIdTransform` | `(id: string) => string` | Custom transform for operation IDs. Receives the raw `operationId` from the spec; return the desired operation name. No additional casing conversion is applied. When omitted, `operationId` values are converted to `camelCase`. |
|
|
311
311
|
| `schemaNameTransform` | `(name: string) => string` | Custom transform for schema (model/enum) names. Applied after the built-in `cleanSchemaName` normalization. Receives the cleaned PascalCase name; return the desired name. |
|
|
312
312
|
| `transformSpec` | `(spec: OpenApiDocument) => OpenApiDocument` | Pre-IR overlay applied to the bundled OpenAPI document before any IR extraction. Use to patch around upstream spec quirks that would otherwise emit a breaking SDK change. See [`transformSpec` — Pre-IR Spec Overlay](advanced/transform-spec.md). |
|
|
313
|
-
| `docUrl` | `string` | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/
|
|
313
|
+
| `docUrl` | `string` | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/users/user)`) are expanded to full URLs (e.g. `[User](https://docs.example.com/reference/users/user)`). |
|
|
314
314
|
| `operationHints` | `Record<string, OperationHint>` | Per-operation overrides keyed by `"METHOD /path"`. Override derived method names, remount to a different service, or split union-body operations into typed wrappers. See [Operation Resolution](architecture/ir-types.md#operation-resolution). |
|
|
315
315
|
| `mountRules` | `Record<string, string>` | Service-level remounting. Maps IR service name to target service/namespace (PascalCase). All operations in the source service are mounted on the target unless overridden per-operation in `operationHints`. |
|
|
316
316
|
| `modelHints` | `Record<string, string>` | Pin specific models to a specific IR service for placement. Maps IR model name (post-`cleanSchemaName`/`schemaNameTransform`) → IR service name (PascalCase). Overrides the default "first service to reference the model wins" assignment. Both names must exist in the parsed spec; unknown names throw at generation time. |
|
|
@@ -113,7 +113,7 @@ When `approved` is `false`, the matching engine skips the approval entirely. Whe
|
|
|
113
113
|
compat: {
|
|
114
114
|
allow: [
|
|
115
115
|
{
|
|
116
|
-
symbol: '
|
|
116
|
+
symbol: 'Acme\\Service\\Users::createUser',
|
|
117
117
|
category: 'parameter_removed',
|
|
118
118
|
match: { parameter: 'passwordHashType' },
|
|
119
119
|
appliesTo: ['php', 'python', 'kotlin', 'dotnet'],
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
{
|
|
15
15
|
"version": 2,
|
|
16
16
|
"language": "php",
|
|
17
|
-
"sdkName": "
|
|
17
|
+
"sdkName": "acme-php",
|
|
18
18
|
"generatedAt": "2026-04-18T22:02:14.077Z",
|
|
19
19
|
"specSha": "sha256:abc123...",
|
|
20
20
|
"specPath": "../openapi-spec/spec/open-api-spec.yaml",
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
| --------------------- | ---------- | -------- | -------------------------------------------------------------------- |
|
|
33
33
|
| `version` | `number` | yes | Manifest schema version (currently `2`) |
|
|
34
34
|
| `language` | `string` | yes | Emitter target language (e.g., `"php"`) |
|
|
35
|
-
| `sdkName` | `string` | no | Human-readable SDK identity (e.g., `"
|
|
35
|
+
| `sdkName` | `string` | no | Human-readable SDK identity (e.g., `"acme-php"`) |
|
|
36
36
|
| `generatedAt` | `string` | yes | ISO-8601 timestamp of the generation run |
|
|
37
37
|
| `specSha` | `string` | no | SHA-256 hash of the source OpenAPI spec |
|
|
38
38
|
| `specPath` | `string` | no | Path or reference to the source spec |
|
package/package.json
CHANGED
|
@@ -11,7 +11,7 @@ Scaffold a complete language emitter for oagen that translates the intermediate
|
|
|
11
11
|
|
|
12
12
|
oagen has a plugin architecture for code generation. Each target language is an **emitter** — a TypeScript module that implements the `Emitter` interface. An emitter receives parsed IR nodes (models, enums, services, etc.) and returns `GeneratedFile[]` — arrays of `{ path, content }` pairs. The engine orchestrator calls each emitter method, prepends a file header, and writes the results to disk.
|
|
13
13
|
|
|
14
|
-
Emitters live in **external projects** (not inside the oagen core repo). They import all oagen types from `@workos/oagen` and are exported through the emitter project's plugin bundle (e.g., `
|
|
14
|
+
Emitters live in **external projects** (not inside the oagen core repo). They import all oagen types from `@workos/oagen` and are exported through the emitter project's plugin bundle (e.g., `acmeEmittersPlugin`), which the consumer project's `oagen.config.ts` imports.
|
|
15
15
|
|
|
16
16
|
## Reference Docs
|
|
17
17
|
|
|
@@ -232,7 +232,7 @@ Add the emitter to the plugin bundle export (e.g., `src/plugin.ts`) and re-expor
|
|
|
232
232
|
```typescript
|
|
233
233
|
// src/plugin.ts
|
|
234
234
|
import { {language}Emitter } from './{language}/index.js';
|
|
235
|
-
export const
|
|
235
|
+
export const acmeEmittersPlugin = {
|
|
236
236
|
emitters: [/* existing, */ {language}Emitter],
|
|
237
237
|
// ...
|
|
238
238
|
};
|
|
@@ -20,4 +20,4 @@ Review this checklist before finalizing the emitter, and when debugging failures
|
|
|
20
20
|
|
|
21
21
|
9. **Wrong test framework** — If the existing SDK uses Jest, generate Jest tests. If it uses pytest, generate pytest tests. Never substitute a different framework because it seems "better."
|
|
22
22
|
|
|
23
|
-
10. **Acronym handling in naming** — `toPascalCase('
|
|
23
|
+
10. **Acronym handling in naming** — `toPascalCase('XMLAPI')` may produce `Xmlapi` instead of `XMLAPI`. If the SDK preserves acronym casing, create an `ensurePascal()` wrapper that only capitalizes the first letter without disturbing the rest.
|
|
@@ -138,7 +138,7 @@ The `sdk:*` scripts bake in `--lang` and `--output` so you only need to pass the
|
|
|
138
138
|
|
|
139
139
|
```bash
|
|
140
140
|
# Fresh generation
|
|
141
|
-
npm run sdk:generate -- --spec ../openapi.yaml --namespace
|
|
141
|
+
npm run sdk:generate -- --spec ../openapi.yaml --namespace acme
|
|
142
142
|
|
|
143
143
|
# Verify generated output
|
|
144
144
|
npm run sdk:verify -- --spec ../openapi.yaml
|
|
@@ -147,13 +147,13 @@ npm run sdk:verify -- --spec ../openapi.yaml
|
|
|
147
147
|
npm run sdk:extract -- --sdk-path ../path-to-live-sdk
|
|
148
148
|
|
|
149
149
|
# Generate with compat overlay (Scenario A)
|
|
150
|
-
npm run sdk:generate -- --spec ../openapi.yaml --namespace
|
|
150
|
+
npm run sdk:generate -- --spec ../openapi.yaml --namespace acme --api-surface ./sdk-{language}-surface.json
|
|
151
151
|
|
|
152
152
|
# Verify with compat check (Scenario A)
|
|
153
153
|
npm run sdk:verify -- --spec ../openapi.yaml --api-surface ./sdk-{language}-surface.json
|
|
154
154
|
|
|
155
155
|
# Integrate into live SDK (Scenario A)
|
|
156
|
-
npm run sdk:generate -- --spec ../openapi.yaml --namespace
|
|
156
|
+
npm run sdk:generate -- --spec ../openapi.yaml --namespace acme --api-surface ./sdk-{language}-surface.json --target ../path-to-live-sdk
|
|
157
157
|
```
|
|
158
158
|
|
|
159
159
|
The `--spec` flag can be replaced by setting `OPENAPI_SPEC_PATH` in the environment.
|
|
@@ -13,7 +13,7 @@ Scaffold a language extractor for oagen's compat verification system. An extract
|
|
|
13
13
|
Live SDK → Extractor → ApiSurface JSON → Differ ← Generated SDK → Violations
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
Each language needs its own extractor because public surface detection is language-specific (e.g., TypeScript exports vs. Ruby public methods vs. Python `__all__` vs. Go capitalized identifiers). An extractor implements the `Extractor` interface and is exported through the emitter project's plugin bundle (e.g., `
|
|
16
|
+
Each language needs its own extractor because public surface detection is language-specific (e.g., TypeScript exports vs. Ruby public methods vs. Python `__all__` vs. Go capitalized identifiers). An extractor implements the `Extractor` interface and is exported through the emitter project's plugin bundle (e.g., `acmeEmittersPlugin`), which the consumer project's `oagen.config.ts` imports.
|
|
17
17
|
|
|
18
18
|
## Reference Docs
|
|
19
19
|
|
|
@@ -120,7 +120,7 @@ Add the extractor to the plugin bundle export (e.g., `src/plugin.ts`) and re-exp
|
|
|
120
120
|
```typescript
|
|
121
121
|
// src/plugin.ts
|
|
122
122
|
import { {language}Extractor } from './compat/extractors/{language}.js';
|
|
123
|
-
export const
|
|
123
|
+
export const acmeEmittersPlugin = {
|
|
124
124
|
extractors: [/* existing, */ {language}Extractor],
|
|
125
125
|
// ...
|
|
126
126
|
};
|
|
@@ -119,7 +119,7 @@ Add the smoke runner path to the plugin bundle export (e.g., `src/plugin.ts`):
|
|
|
119
119
|
|
|
120
120
|
```typescript
|
|
121
121
|
// src/plugin.ts
|
|
122
|
-
export const
|
|
122
|
+
export const acmeEmittersPlugin = {
|
|
123
123
|
smokeRunners: {
|
|
124
124
|
// existing runners...
|
|
125
125
|
{language}: path.join(smokeDir, 'sdk-{language}.ts'),
|
|
@@ -42,7 +42,7 @@ Collect these values. Use arguments if provided, otherwise ask:
|
|
|
42
42
|
2. **`spec`** — path to the OpenAPI spec (e.g., `../openapi.yaml`)
|
|
43
43
|
3. **`output`** — path to the generated SDK output directory
|
|
44
44
|
4. **`project`** — path to the emitter project (often the parent of `output`)
|
|
45
|
-
5. **`namespace`** — SDK namespace/package name (e.g., `
|
|
45
|
+
5. **`namespace`** — SDK namespace/package name (e.g., `Acme`)
|
|
46
46
|
|
|
47
47
|
Optional (Scenario A only):
|
|
48
48
|
|