@workos/oagen 0.12.0 → 0.13.0

package/dist/verify/index.d.mts

@@ -1,5 +1,5 @@
 import { Bt as CompatPolicyHints, _t as ApiSurface, t as ApiSpec, wt as Violation } from "../types-BL762XqW.mjs";
-import { t as CompatDiffResult } from "../differ-BTx-rDgJ.mjs";
+import { t as CompatDiffResult } from "../differ-fdF9qogA.mjs";
 
 //#region src/verify/types.d.ts
 interface VerifyDiagnostics {

package/dist/verify/index.mjs

@@ -1,6 +1,6 @@
 import { m as CommandError } from "../tree-sitter-DcUvm0KA.mjs";
-import { a as MANIFEST_FILENAME, i as generate, n as getEmitter, t as diffSpecs } from "../diff-CihuFSbJ.mjs";
-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-DTaApIqN.mjs";
+import { a as MANIFEST_FILENAME, i as generate, n as getEmitter, t as diffSpecs } from "../diff-C38px0NK.mjs";
+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-xp7F8_dW.mjs";
 import * as path$1 from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";

package/docs/advanced/index.md

@@ -8,4 +8,5 @@ Use this section when you need to preserve an existing SDK surface, verify behav
 - [Extractor Contract](../architecture/extractor-contract.md)
 - [Non-Additive Changes](../architecture/non-additive-changes.md)
 - [`@oagen-ignore` — Preserving Hand-Written Code](./oagen-ignore.md)
+- [`transformSpec` — Pre-IR Spec Overlay](./transform-spec.md)
 - [CLI Reference](../cli.md)

package/docs/advanced/transform-spec.md

@@ -0,0 +1,124 @@
+# `transformSpec` — Pre-IR Spec Overlay
+
+`transformSpec` is a function on `OagenConfig` (and `ParseOptions`) that runs once on the bundled OpenAPI document, after `$ref` bundling and before any IR extraction. Use it to patch around upstream spec quirks that would otherwise emit a breaking SDK change.
+
+## Signature
+
+```typescript
+import type { OagenConfig, OpenApiDocument } from "@workos/oagen";
+
+const config: OagenConfig = {
+  // ...
+  transformSpec(spec: OpenApiDocument): OpenApiDocument {
+    // mutate `spec` in place and return it, or return a new object
+    return spec;
+  },
+};
+```
+
+`OpenApiDocument` is `Record<string, unknown>` — intentionally loose so the transform can reach extension keys without fighting types. Narrow with `as` at use sites.
+
+## When to use it
+
+`transformSpec` is an emergency lever, not a routine knob. Reach for it when:
+
+1. **The upstream spec can't be changed in time.** The right fix is almost always to amend the spec author's PR. `transformSpec` is for when you can't, and the SDK ships tomorrow.
+2. **The change is genuinely additive at the schema level but the spec authoring expressed it as a fork.** The canonical example is below.
+3. **You need a one-shot adapter** for an OpenAPI extension, vendor extension, or non-conforming construct that oagen doesn't natively model.
+
+If you find yourself reaching for `transformSpec` repeatedly for the same pattern, that's a signal the underlying issue belongs upstream — either in the spec authoring style or as a feature request to oagen.
+
+## Canonical example: schema-fork rescue
+
+The pattern: an upstream PR forks a new schema (`FooWithBar`) instead of adding a field to the existing one (`Foo`), and re-points a path's response `$ref` at the fork. Because the schema name is part of the SDK's public surface in typed languages, this changes the return type of every method that uses it — a breaking change in Go, Kotlin, .NET, etc.
+
+oagen's compat differ flags this pattern via the `remediation` hint on classified changes (see `docs/core/compatibility-policy.md`). The hint nudges spec authors to fix it upstream. When you can't wait for that fix, `transformSpec` un-forks the schema at parse time:
+
+```typescript
+// oagen.config.ts
+import type { OagenConfig } from "@workos/oagen";
+
+const config: OagenConfig = {
+  transformSpec(spec) {
+    const components = (
+      spec as {
+        components?: {
+          schemas?: Record<
+            string,
+            { properties?: Record<string, unknown>; required?: string[] }
+          >;
+        };
+      }
+    ).components;
+    const paths = (
+      spec as {
+        paths?: Record<
+          string,
+          Record<
+            string,
+            {
+              responses?: Record<
+                string,
+                { content?: Record<string, { schema?: { $ref?: string } }> }
+              >;
+            }
+          >
+        >;
+      }
+    ).paths;
+
+    // 1. Rewrite the path response refs back to the original schema.
+    const forkedRef = "#/components/schemas/FooWithBarList";
+    const originalRef = "#/components/schemas/FooList";
+    for (const pathItem of Object.values(paths ?? {})) {
+      for (const op of Object.values(pathItem)) {
+        const ref =
+          op?.responses?.["200"]?.content?.["application/json"]?.schema?.$ref;
+        if (
+          ref === forkedRef &&
+          op.responses?.["200"]?.content?.["application/json"]?.schema
+        ) {
+          op.responses["200"].content["application/json"].schema!.$ref =
+            originalRef;
+        }
+      }
+    }
+
+    // 2. Add the forked schema's new fields to the original schema additively.
+    const foo = components?.schemas?.Foo;
+    if (foo?.properties) {
+      foo.properties.bar = {
+        $ref: "#/components/schemas/Bar",
+      } as unknown as Record<string, unknown>;
+    }
+
+    // 3. Drop the now-orphaned forked schemas so they don't bloat the IR.
+    if (components?.schemas) {
+      delete components.schemas.FooWithBar;
+      delete components.schemas.FooWithBarList;
+    }
+
+    return spec;
+  },
+};
+
+export default config;
+```
+
+The result: typed SDKs see no return-type change. Existing callers compile against the same struct/class, and the new `bar` field is available as an additive property.
+
+## When the hook runs
+
+- **After:** OpenAPI doc load, `$ref` bundling (`@redocly/openapi-core`), and OpenAPI version validation.
+- **Before:** schema extraction, operation extraction, inline-model normalization, and IR validation.
+
+This means anything you do to `spec.components.schemas`, `spec.paths`, or `spec.servers` flows naturally into the IR. Internal `$ref`s are still strings at this point — they aren't dereferenced until extraction.
+
+If you need to inspect the resulting IR instead, post-process the `ApiSpec` returned by `parseSpec`. `transformSpec` is intentionally narrow.
+
+## Caveats
+
+- **Not for backward-compat hacks.** If a server-side change is a real shape change (not a fork), don't paper over it here — fix the SDK instead.
+- **Idempotence is your responsibility.** The hook may run more than once per CLI session (e.g. `verify` parses the spec twice when `--old-spec` is provided). Write transforms that no-op cleanly when applied to an already-patched document.
+- **No type narrowing.** `OpenApiDocument` is intentionally `Record<string, unknown>`. Cast aggressively at use sites; the alternative would be importing OpenAPI's full type tree, which we deliberately avoid in oagen's public surface.
+- **Surfaces in every command.** `parse`, `generate`, `diff`, `resolve`, `verify`, and `compat-extract` all honor `transformSpec` from the config file.

package/docs/cli.md

@@ -301,15 +301,16 @@ export default config;
 
 ### Options
 
-| Key                    | Type                            | Description                                                                                                                                                                                                                                                                                                                   |
-| ---------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `emitters`             | `Emitter[]`                     | Language emitters to register. Each emitter implements the `Emitter` interface and generates SDK files for one target language.                                                                                                                                                                                               |
-| `extractors`           | `Extractor[]`                   | API surface extractors to register. Each extractor parses a live SDK and produces an `ApiSurface` JSON used for compat verification.                                                                                                                                                                                          |
-| `emitterProject`       | `string`                        | Path to the emitter project directory. Used by skills to scaffold new emitters, tests, and smoke runners in the correct location.                                                                                                                                                                                             |
-| `smokeRunners`         | `Record<string, string>`        | Map from language key to custom smoke runner script path. Overrides the built-in `sdk-test.ts` for `oagen verify`. Can also be set per-invocation with `--smoke-runner`.                                                                                                                                                      |
-| `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`.                                                                                             |
-| `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.                                                                                                                                                    |
-| `docUrl`               | `string`                        | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/authkit/user)`) are expanded to full URLs (e.g. `[User](https://workos.com/docs/reference/authkit/user)`).                                                                                                       |
-| `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).                                                                              |
-| `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`.                                                                                                                  |
-| `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. |
+| Key                    | Type                                         | Description                                                                                                                                                                                                                                                                                                                   |
+| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `emitters`             | `Emitter[]`                                  | Language emitters to register. Each emitter implements the `Emitter` interface and generates SDK files for one target language.                                                                                                                                                                                               |
+| `extractors`           | `Extractor[]`                                | API surface extractors to register. Each extractor parses a live SDK and produces an `ApiSurface` JSON used for compat verification.                                                                                                                                                                                          |
+| `emitterProject`       | `string`                                     | Path to the emitter project directory. Used by skills to scaffold new emitters, tests, and smoke runners in the correct location.                                                                                                                                                                                             |
+| `smokeRunners`         | `Record<string, string>`                     | Map from language key to custom smoke runner script path. Overrides the built-in `sdk-test.ts` for `oagen verify`. Can also be set per-invocation with `--smoke-runner`.                                                                                                                                                      |
+| `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`.                                                                                             |
+| `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.                                                                                                                                                    |
+| `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).                                                                           |
+| `docUrl`               | `string`                                     | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/authkit/user)`) are expanded to full URLs (e.g. `[User](https://workos.com/docs/reference/authkit/user)`).                                                                                                       |
+| `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).                                                                              |
+| `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`.                                                                                                                  |
+| `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. |

package/docs/core/compatibility-policy.md

@@ -168,3 +168,29 @@ The `failOn` level determines which unapproved changes cause `oagen verify` to f
 | `none`      | Never fails for compat                   |
 | `breaking`  | Unapproved breaking changes              |
 | `soft-risk` | Unapproved breaking OR soft-risk changes |
+
+## Remediation Hints
+
+Some changes have a recognized upstream root cause that the spec author can fix. When the differ detects one, it attaches a `remediation` string to the classified change. The hint surfaces in both the machine-readable report (`CompatReportChange.remediation`) and the human-readable summary (printed as `hint: ...` underneath the change).
+
+The classification, severity, and fail-threshold semantics are unchanged — `remediation` is purely advisory, telling the spec author how to make the change non-breaking.
+
+### Detected patterns
+
+| Pattern         | Trigger                                                                                                                                                                                  | Hint                                                                                                                                                                                                                                              |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Schema fork** | A `return_type_changed` or `field_type_changed` where the new type was newly added in the candidate snapshot _and_ its field set is a non-strict superset of the prior type's field set. | "Schema `NewType` looks like `OldType` with additional fields. Consider adding the new fields to `OldType` instead of forking a new schema." Forking forces a breaking type-name change in typed SDKs; extending the existing schema is additive. |
+
+### Example: schema fork
+
+A path's response `$ref` is redirected from `MembershipBaseList` to a brand-new `MembershipBaseWithUserList` whose only difference is an added `user` field. The differ reports a `return_type_changed` (breaking) for the affected method, plus the remediation hint pointing the spec author at the additive alternative.
+
+If the upstream fix can't land in time, `transformSpec` is the local escape hatch — see [`transformSpec` — Pre-IR Spec Overlay](../advanced/transform-spec.md).
+
+### Adding new patterns
+
+Detection rules live in `detectForkedSchemas` (`src/compat/differ.ts`). To add a rule:
+
+1. Add a heuristic that examines the existing `changes` list plus the baseline/candidate snapshots.
+2. When the pattern matches, set `change.remediation` on the relevant existing change. Don't introduce a new change for the same pattern — pile remediation onto what's already classified.
+3. Keep the rule scoped: it should match a recognizable upstream antipattern, not generic shape changes.

package/docs/core/compatibility.md

@@ -74,6 +74,12 @@ Each classified change includes a provenance bucket explaining where the drift c
 - `normalization_change` — Naming normalization produced different output
 - `unknown` — Source of drift not determined
 
+### Remediation Hints
+
+When a change matches a recognized upstream antipattern (e.g. forking a new schema instead of extending the existing one), the differ attaches a `remediation` string to the classified change. The hint surfaces in both the machine-readable report and the human-readable summary, telling the spec author how to make the change non-breaking. The classification, severity, and fail-threshold semantics are unchanged.
+
+See [Compatibility Policy → Remediation Hints](compatibility-policy.md#remediation-hints) for the list of detected patterns and how to add new ones.
+
 ## Further Reading
 
 - [CLI Reference](../cli.md) — `compat-extract`, `compat-diff`, `compat-summary` argument tables

package/docs/index.md

@@ -21,6 +21,7 @@ Read these when you need migration or verification workflows beyond basic genera
 - [Workflows](architecture/workflows.md)
 - [Extractor Contract](architecture/extractor-contract.md)
 - [Non-Additive Changes](architecture/non-additive-changes.md)
+- [`transformSpec` — Pre-IR Spec Overlay](advanced/transform-spec.md)
 
 ## Agent Task Guides
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Framework for building OpenAPI SDK emitters",
   "author": "WorkOS",
   "license": "MIT",