@scalar/openapi-validator 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @scalar/openapi-validator
 
+## 0.1.2
+
+### Patch Changes
+
+- [#10202](https://github.com/scalar/scalar/pull/10202): Explain invalid URI references and OpenAPI component names, and return parser errors for malformed reference escapes.
+- [#10158](https://github.com/scalar/scalar/pull/10158): Add regression coverage for duplicate required property names.
+- [#10136](https://github.com/scalar/scalar/pull/10136): Restore modal and single-file reference tests, update layout selectors, and remove stale comments. Named-resource resolution remains unsupported and is tested explicitly.
+
+## 0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/explain-component-references.d.ts

@@ -0,0 +1,8 @@
+import type { AnyObject } from '@scalar/types/utils';
+import type { ErrorObject } from './types.js';
+/**
+ * Encoding a URI does not make an invalid OpenAPI component name valid. Keep
+ * this guidance in the OpenAPI layer so other JSON Schema users do not see it.
+ */
+export declare const explainComponentReferences: (errors: ErrorObject[], specification: AnyObject) => ErrorObject[];
+//# sourceMappingURL=explain-component-references.d.ts.map

package/dist/explain-component-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-component-references.d.ts","sourceRoot":"","sources":["../src/explain-component-references.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,WAAW,EAAE,EAAE,eAAe,SAAS,KAAG,WAAW,EAmCpG,CAAA"}

package/dist/explain-component-references.js

@@ -0,0 +1,34 @@
+import { getValueAtPath } from '@scalar/helpers/object/get-value-at-path';
+/**
+ * Encoding a URI does not make an invalid OpenAPI component name valid. Keep
+ * this guidance in the OpenAPI layer so other JSON Schema users do not see it.
+ */
+export const explainComponentReferences = (errors, specification) => errors.map((error) => {
+    if (typeof error.path !== 'string' || !error.path.endsWith('/$ref') || typeof specification.openapi !== 'string') {
+        return error;
+    }
+    // Ajv paths are JSON Pointers, not URI fragments: preserve percent signs.
+    const segments = error.path
+        .split('/')
+        .slice(1)
+        .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));
+    const reference = getValueAtPath(specification, segments);
+    if (typeof reference !== 'string' || !reference.startsWith('#')) {
+        return error;
+    }
+    // A malformed escape already has URI guidance; do not guess its target name.
+    try {
+        // Decode the fragment before splitting: an encoded slash is a separator.
+        const component = decodeURIComponent(reference.slice(1)).match(/^\/components\/(?:schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems|mediaTypes)\/([^/]*)/)?.[1];
+        if (component === undefined || /^[a-zA-Z0-9._-]+$/.test(component)) {
+            return error;
+        }
+    }
+    catch {
+        return error;
+    }
+    return {
+        ...error,
+        message: `${error.message} OpenAPI component names must match "^[a-zA-Z0-9._-]+$". Rename the component and update its references; percent-encoding alone does not fix the component name.`,
+    };
+});

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAKpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAGpE,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG;IACjD;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B,CAAA;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CAEnG"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAMpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAGpE,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG;IACjD;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B,CAAA;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CAEnG"}

package/dist/validate.js

@@ -1,6 +1,7 @@
 import { createSpecificationValidator } from '@scalar/json-schema-validator';
 import { detectVersion } from './detect-version.js';
 import { ERRORS } from './errors.js';
+import { explainComponentReferences } from './explain-component-references.js';
 import { OpenApiSpecifications } from './specifications.js';
 import { validatePathParameters } from './validate-path-parameters.js';
 const validateDocument = createSpecificationValidator({
@@ -9,6 +10,7 @@ const validateDocument = createSpecificationValidator({
     // OpenAPI 3.1 and 3.2 use the media-range format.
     formats: (version) => (version === '3.1' || version === '3.2' ? { 'media-range': true } : undefined),
     errors: { emptyOrInvalid: ERRORS.EMPTY_OR_INVALID, versionNotSupported: ERRORS.OPENAPI_VERSION_NOT_SUPPORTED },
+    transformErrors: explainComponentReferences,
     // Path-template semantics that the JSON schema cannot express. These need a
     // fully resolved document (a path parameter can be declared via `$ref`), so
     // they are opt-in: callers that resolve references first can enable them.

package/package.json

@@ -17,7 +17,7 @@
     "validator",
     "typescript"
   ],
-  "version": "0.1.0",
+  "version": "0.1.2",
   "engines": {
     "node": ">=22"
   },
@@ -39,9 +39,9 @@
   "sideEffects": false,
   "dependencies": {
     "yaml": "^2.9.0",
-    "@scalar/types": "0.18.3",
-    "@scalar/json-schema-validator": "0.1.0",
-    "@scalar/helpers": "0.11.2"
+    "@scalar/json-schema-validator": "0.1.2",
+    "@scalar/helpers": "0.12.0",
+    "@scalar/types": "0.20.0"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -50,7 +50,7 @@
     "tailwindcss": "^4.3.3",
     "vite": "8.1.5",
     "vue": "^3.5.40",
-    "@scalar/themes": "0.17.4",
+    "@scalar/themes": "0.18.0",
     "@scalar/use-codemirror": "0.14.15"
   },
   "scripts": {