@stdy/cli 0.15.2 → 0.16.0

package/README.md

@@ -36,6 +36,12 @@ steady api.yaml
 # Validate spec without starting server
 steady validate api.yaml
 
+# Explain a diagnostic code
+steady explain E3008
+
+# List all diagnostic codes
+steady explain
+
 # Watch for spec changes
 steady -r api.yaml
 
@@ -50,6 +56,7 @@ steady [command] [options] <spec-file>
 
 Commands:
   validate <spec>    Validate an OpenAPI spec (doesn't start server)
+  explain [code...]  Explain diagnostic codes (e.g., steady explain E3008)
   <spec>             Start mock server (default)
 
 Options:
@@ -59,14 +66,18 @@ Options:
   --log-level <level>     summary | details | full (default: summary)
   --log-bodies            Show request/response bodies
   --log=false             Disable request logging
-  --strict                Reject invalid requests (default)
-  --relaxed               Log warnings but return responses anyway
+  --reject-on-sdk-error   Return 400 for SDK issues instead of mock response
+  --fail-on-ambiguous     Exit 1 if any ambiguous diagnostics found (CI mode)
+  --fail-on-warnings      Exit 1 if any warning-level diagnostics found (CI mode)
+  --no-color              Disable colored output (also respects NO_COLOR env)
   -h, --help              Show help
 
 Validator Options:
   --validator-strict-oneof             Require exactly one oneOf variant to match
   --validator-query-array-format=<fmt> Array query param serialization (see below)
   --validator-query-object-format=<fmt> Object query param serialization (see below)
+  --validator-form-array-format=<fmt>  Array form field serialization (see below)
+  --validator-form-object-format=<fmt> Object form field serialization (see below)
 
 Generator Options:
   --generator-array-size=<n>   Exact size for all generated arrays
@@ -103,6 +114,32 @@ per-request via headers.
 | `brackets`   | `id[role]=admin&id[firstName]=Alex` | `style=deepObject`          |
 | `dots`       | `id.role=admin&id.firstName=Alex`   | Non-standard (SDK compat)   |
 
+### Form Parameter Serialization
+
+Form body parameters (application/x-www-form-urlencoded) use the same formats as
+query parameters. Configure via CLI flags or per-request headers.
+
+**Array formats** (`--validator-form-array-format`):
+
+| Format     | Example                  | OpenAPI Equivalent             |
+| ---------- | ------------------------ | ------------------------------ |
+| `auto`     | Read from spec (default) | -                              |
+| `repeat`   | `tags=a&tags=b`          | `style=form, explode=true`     |
+| `comma`    | `tags=a,b`               | `style=form, explode=false`    |
+| `space`    | `tags=a%20b`             | `style=spaceDelimited`         |
+| `pipe`     | `tags=a\|b`              | `style=pipeDelimited`          |
+| `brackets` | `tags[]=a&tags[]=b`      | PHP/Rails style (non-standard) |
+
+**Object formats** (`--validator-form-object-format`):
+
+| Format       | Example                        | OpenAPI Equivalent          |
+| ------------ | ------------------------------ | --------------------------- |
+| `auto`       | Read from spec (default)       | -                           |
+| `flat`       | `name=sam&age=30`              | `style=form, explode=true`  |
+| `flat-comma` | `id=role,admin,firstName,Alex` | `style=form, explode=false` |
+| `brackets`   | `user[name]=sam`               | `style=deepObject`          |
+| `dots`       | `user.name=sam`                | Non-standard (SDK compat)   |
+
 ### Port Configuration
 
 The server port is determined in this order:
@@ -150,7 +187,7 @@ responses:
 
 ## Request Validation
 
-In `--strict` mode (default), requests are validated against:
+Requests are validated against:
 
 - **Path parameters** - type coercion and schema validation
 - **Query parameters** - required check, type validation
@@ -158,8 +195,9 @@ In `--strict` mode (default), requests are validated against:
 - **Cookies** - required cookies, schema validation
 - **Request body** - JSON Schema validation, content-type check
 
-Invalid requests return 400 with validation errors. In `--relaxed` mode,
-validation errors are logged but responses are still returned.
+By default, validation issues are reported in `X-Steady-*` response headers
+while still returning mock responses. Use `--reject-on-sdk-error` to return 400
+for SDK issues (structural validation failures) instead.
 
 ### Request Headers
 
@@ -167,9 +205,11 @@ Override server behavior for individual requests:
 
 | Header                         | Description                                          |
 | ------------------------------ | ---------------------------------------------------- |
-| `X-Steady-Mode`                | Override validation mode: `strict` or `relaxed`      |
+| `X-Steady-Reject-On-Error`     | `true` to return 400 for SDK issues on this request  |
 | `X-Steady-Query-Array-Format`  | Override array query param serialization format      |
 | `X-Steady-Query-Object-Format` | Override object query param serialization format     |
+| `X-Steady-Form-Array-Format`   | Override array form field serialization format       |
+| `X-Steady-Form-Object-Format`  | Override object form field serialization format      |
 | `X-Steady-Array-Size`          | Override array size (sets both min and max)          |
 | `X-Steady-Array-Min`           | Override minimum array size                          |
 | `X-Steady-Array-Max`           | Override maximum array size                          |
@@ -178,8 +218,8 @@ Override server behavior for individual requests:
 | `X-Steady-Stream-Interval-Ms`  | Interval between streamed items in ms (default: 100) |
 
 ```bash
-# Force strict validation
-curl -H "X-Steady-Mode: strict" http://localhost:3000/users
+# Reject SDK issues for this request
+curl -H "X-Steady-Reject-On-Error: true" http://localhost:3000/users
 
 # Request 50 items in arrays
 curl -H "X-Steady-Array-Size: 50" http://localhost:3000/users
@@ -197,7 +237,8 @@ Informational headers returned by the server:
 
 | Header                    | Description                                           |
 | ------------------------- | ----------------------------------------------------- |
-| `X-Steady-Mode`           | The validation mode used for this request             |
+| `X-Steady-Valid`          | Whether the request passed SDK validation             |
+| `X-Steady-Error-Count`    | Number of diagnostic issues found                     |
 | `X-Steady-Matched-Path`   | The OpenAPI path pattern that matched                 |
 | `X-Steady-Example-Source` | How the response was generated: `generated` or `none` |
 | `X-Steady-Streaming`      | Set to `true` for streaming responses                 |
@@ -356,22 +397,26 @@ Supports JSON Schema draft 2020-12 with ~91% compliance.
 - `$dynamicRef` / `$dynamicAnchor`
 - External `$ref` (http://, file://)
 
-## Error Attribution
+## Diagnostics
 
-Errors indicate whether the issue is likely in the spec or the client request:
+Steady attributes every validation issue to a responsible party — SDK, spec, or
+ambiguous — using compiler-style output:
 
 ```
-POST /users → 400 Bad Request
-
-Validation errors:
-  1. Required parameter missing
-     Path: query.limit
-     Expected: integer
-
-Attribution: SDK issue (high confidence)
-Suggestion: Check SDK implementation - required parameter not sent
+error[E3002]: Missing required query parameter
+ --> GET /users
+  |
+  |  Required parameter 'limit' not found in query string
+  |
+  = expected: query parameter 'limit' (type: integer)
+  = Add the required parameter to the request
+
+For details, try: steady explain E3002
 ```
 
+Use `steady explain <code>` for detailed documentation on any diagnostic code,
+including what it means, why it's categorized that way, and what to do about it.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stdy/cli",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "OpenAPI 3 mock server. Validates SDKs against OpenAPI specs with clear error attribution.",
   "license": "Elastic-2.0",
   "repository": {
@@ -29,10 +29,10 @@
     "node": ">=14.0.0"
   },
   "optionalDependencies": {
-    "@stdy/cli-linux-x64": "0.15.2",
-    "@stdy/cli-linux-arm64": "0.15.2",
-    "@stdy/cli-darwin-x64": "0.15.2",
-    "@stdy/cli-darwin-arm64": "0.15.2",
-    "@stdy/cli-win32-x64": "0.15.2"
+    "@stdy/cli-linux-x64": "0.16.0",
+    "@stdy/cli-linux-arm64": "0.16.0",
+    "@stdy/cli-darwin-x64": "0.16.0",
+    "@stdy/cli-darwin-arm64": "0.16.0",
+    "@stdy/cli-win32-x64": "0.16.0"
   }
 }