@workos/oagen 0.3.0 → 0.5.0

package/docs/cli.md

@@ -122,6 +122,25 @@ oagen parse --spec openapi.yml
 | --------------- | -------- | ----------------------- | ------------------------------------------------ |
 | `--spec <path>` | No       | `OPENAPI_SPEC_PATH` env | Path to an OpenAPI 3.x spec file (YAML or JSON). |
 
+## `oagen resolve`
+
+Resolve operation names from the spec using the algorithm and optional hints. Outputs a review table (markdown) or JSON for programmatic use.
+
+```bash
+# Markdown review table (default)
+oagen resolve --spec openapi.yml
+
+# JSON output for CI/scripting
+oagen resolve --spec openapi.yml --format json
+```
+
+| Argument            | Required | Default                 | Description                                      |
+| ------------------- | -------- | ----------------------- | ------------------------------------------------ |
+| `--spec <path>`     | No       | `OPENAPI_SPEC_PATH` env | Path to an OpenAPI 3.x spec file (YAML or JSON). |
+| `--format <format>` | No       | `table`                 | Output format: `table` (markdown) or `json`.     |
+
+When `oagen.config.ts` defines `operationHints` and/or `mountRules`, they are applied automatically. The table format flags operations that have no hint and are resolved purely by algorithm.
+
 ## Configuration (`oagen.config.ts`)
 
 Place an `oagen.config.ts` (or `.js`/`.mjs`) in your project root to register emitters, extractors, and customize pipeline behavior. The CLI loads this file at startup before any command runs.
@@ -142,11 +161,13 @@ 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`. |
-| `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)`).           |
+| 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`.                |
+| `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`.                                     |

package/docs/core/minimal-emitter.md

@@ -71,10 +71,6 @@ export const demoEmitter: Emitter = {
     return [];
   },
 
-  generateConfig(): GeneratedFile[] {
-    return [];
-  },
-
   generateTypeSignatures(): GeneratedFile[] {
     return [];
   },

package/docs/core/quickstart.md

@@ -105,7 +105,6 @@ export const demoEmitter: Emitter = {
     },
   ],
   generateErrors: () => [],
-  generateConfig: () => [],
   generateTypeSignatures: () => [],
   generateTests: () => [],
   fileHeader: () => "# Generated by oagen",

package/examples/reference-emitter/README.md

@@ -9,7 +9,6 @@ A minimal but working TypeScript emitter for oagen, demonstrating the Emitter in
 - `generateResources` — resource classes using `planOperation`
 - `generateClient` — top-level client with resource accessors
 - `generateErrors` — error class hierarchy
-- `generateConfig` — config types and base resource class
 - Type mapping via `mapTypeRef`
 
 ## What it does NOT cover

package/examples/reference-emitter/src/emitter.ts

@@ -4,7 +4,6 @@ import { generateEnums } from './generators/enums.js';
 import { generateResources } from './generators/resources.js';
 import { generateClient } from './generators/client.js';
 import { generateErrors } from './generators/errors.js';
-import { generateConfig } from './generators/config.js';
 import { generateTests } from './generators/tests.js';
 
 /**
@@ -38,10 +37,6 @@ export const typescriptEmitter: Emitter = {
     return generateErrors(ctx);
   },
 
-  generateConfig(ctx: EmitterContext): GeneratedFile[] {
-    return generateConfig(ctx);
-  },
-
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
     return generateTests(spec, ctx);
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Framework for building OpenAPI SDK emitters",
   "author": "WorkOS",
   "license": "MIT",
@@ -74,7 +74,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^1.34.3",
+    "@redocly/openapi-core": "^2.25.1",
     "commander": "^13.1.0",
     "dotenv": "^17.3.1",
     "tree-sitter": "^0.21.1",
@@ -94,12 +94,12 @@
     "@commitlint/cli": "^20.5.0",
     "@commitlint/config-conventional": "^20.5.0",
     "@types/node": "^25.3.3",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.1.2",
     "husky": "^9.1.7",
     "oxfmt": "^0.36.0",
     "oxlint": "^1.51.0",
     "prettier": "^3.8.1",
     "tsdown": "^0.21.5",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.2"
   }
 }

package/skills/review-operations/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: review-operations
+description: >-
+  Review resolved operation names from the OpenAPI spec. Runs the resolution
+  algorithm with hints applied and outputs a review table for human approval.
+  Use when reviewing operation names, checking for unhinted operations, auditing
+  method naming, or after spec changes. Also triggers for "operation names",
+  "method names", "hint map", "operation review", "unhinted operations".
+---
+
+# /review-operations
+
+Parse the OpenAPI spec, run operation resolution with the configured hint map, and produce a review table highlighting operations that need attention.
+
+## Accept Arguments
+
+Accept `--spec <path>` as an optional argument. If not provided, fall back to the `OPENAPI_SPEC_PATH` environment variable, then try `../openapi-spec/spec/open-api-spec.yaml`.
+
+## Step 1: Resolve Paths
+
+1. **Spec path**: from argument, `OPENAPI_SPEC_PATH` env, or `../openapi-spec/spec/open-api-spec.yaml`
+2. **oagen-emitters project**: check if `oagen.config.ts` exists in the current directory. If not, use `AskUserQuestion`: "Where is your oagen-emitters project?"
+3. Validate the spec file exists before proceeding.
+
+## Step 2: Run Resolution
+
+Run `oagen resolve` to get the full resolution output:
+
+```bash
+npx oagen resolve --spec <path> --format json
+```
+
+Parse the JSON output. Each entry has: `service`, `method`, `path`, `derivedName`, `hintApplied`, `mountOn`, `wrappers`.
+
+## Step 3: Categorize Operations
+
+Sort operations into three categories:
+
+1. **Hinted** — operations with an explicit name or mount override in `operationHints` or `mountRules`
+2. **Algorithm-derived (look good)** — unhinted operations where the derived name follows standard CRUD patterns and reads naturally
+3. **Needs review** — unhinted operations where the derived name may be suboptimal:
+   - Plural names for single-resource POST/PUT/PATCH/DELETE (e.g., `create_organizations` instead of `create_organization`)
+   - Names using `list_` for non-collection GETs (e.g., `list_profile`)
+   - Generic names like `create_token` that don't capture the operation's purpose
+   - Names with deeply nested paths that lose context
+
+## Step 4: Output Review Table
+
+Print a markdown table with all operations, grouped by category:
+
+```markdown
+## Operations needing review (N)
+
+| Service | Method | Path | Current Name | Suggested Action |
+| ------- | ------ | ---- | ------------ | ---------------- |
+
+## Algorithm-derived operations (N)
+
+| Service | Method | Path | Derived Name | Mount On |
+| ------- | ------ | ---- | ------------ | -------- |
+
+## Hinted operations (N)
+
+| Service | Method | Path | Hint Name | Mount On |
+| ------- | ------ | ---- | --------- | -------- |
+```
+
+For "needs review" operations, suggest a concrete action:
+
+- `add name hint: <suggested_name>` for semantic renames
+- `add mountOn hint: <target>` for service remounting
+- `singularize: <name>` for plural-to-singular fixes
+
+## Step 5: Summary
+
+Print a summary:
+
+- Total operations
+- Hinted (with name or mount overrides)
+- Algorithm-derived (no action needed)
+- Needs review (may need hints)
+
+If there are operations needing review, ask the user: "Would you like me to add hints for any of these operations to `oagen.config.ts`?"