@stdy/cli 0.15.3 → 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,8 +66,10 @@ 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:
@@ -178,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
@@ -186,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
 
@@ -195,7 +205,7 @@ 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       |
@@ -208,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
@@ -227,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                 |
@@ -386,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.3",
+  "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.3",
-    "@stdy/cli-linux-arm64": "0.15.3",
-    "@stdy/cli-darwin-x64": "0.15.3",
-    "@stdy/cli-darwin-arm64": "0.15.3",
-    "@stdy/cli-win32-x64": "0.15.3"
+    "@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"
   }
 }