api-quality-spectral-ruleset 1.5.0 → 1.6.0-beta.2

package/functions/apq-tags-consistency.js

@@ -0,0 +1,71 @@
+/**
+ * @param {object} given - the whole document ($)
+ * @param {object} options - unused
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const errors = [];
+  const doc = given || {};
+  const tags = Array.isArray(doc.tags) ? doc.tags : [];
+
+  if (tags.length === 0) {
+    return [{
+      message: 'OAR047: Add tags with a short description to each one.',
+      path: ['tags'],
+    }];
+  }
+
+  const declaredNames = new Set();
+
+  tags.forEach((tag, index) => {
+    if (!tag || typeof tag !== 'object') return;
+    const { name, description } = tag;
+
+    if (typeof name === 'string' && name.length > 0) {
+      if (declaredNames.has(name)) {
+        errors.push({
+          message: 'OAR047: Remove this duplicate tag',
+          path: ['tags', index, 'name'],
+        });
+      } else {
+        declaredNames.add(name);
+      }
+    } else {
+      errors.push({
+        message: 'OAR047: Add tags with a short description to each one.',
+        path: ['tags', index],
+      });
+    }
+
+    if (typeof description !== 'string' || description.trim().length === 0) {
+      errors.push({
+        message: 'OAR047: Add a short description to this tag',
+        path: ['tags', index, 'description'],
+      });
+    }
+  });
+
+  const verbs = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
+  const walkOperations = (paths, rootKey) => {
+    Object.entries(paths || {}).forEach(([pathKey, pathItem]) => {
+      if (!pathItem || typeof pathItem !== 'object') return;
+      verbs.forEach((verb) => {
+        const operation = pathItem[verb];
+        if (!operation || typeof operation !== 'object' || !Array.isArray(operation.tags)) return;
+        operation.tags.forEach((tagName, tagIndex) => {
+          if (typeof tagName === 'string' && !declaredNames.has(tagName)) {
+            errors.push({
+              message: 'OAR047: This tag should be declared in the tags section of the contract',
+              path: [rootKey, pathKey, verb, 'tags', tagIndex],
+            });
+          }
+        });
+      });
+    });
+  };
+
+  walkOperations(doc.paths, 'paths');
+  if (doc.webhooks) walkOperations(doc.webhooks, 'webhooks');
+
+  return errors;
+};

package/functions/apq-total-param-default-value.js

@@ -0,0 +1,24 @@
+/**
+ * @param {object} given - the matched $total parameter (already resolved by Spectral)
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') return [];
+
+  const doc = context.document?.data ?? {};
+  const isOAP2 = typeof doc.swagger === 'string';
+
+  const defaultValue = isOAP2 ? given.default : given.schema && given.schema.default;
+
+  if (defaultValue === undefined || defaultValue === false) return [];
+
+  const path = isOAP2
+    ? [...context.path, 'default']
+    : [...context.path, 'schema', 'default'];
+
+  return [{
+    message: 'OAR026: The $total parameter default value should be false.',
+    path,
+  }];
+};

package/functions/apq-undefined-response-media-type.js

@@ -0,0 +1,46 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+
+const BODY_ALLOWED_METHODS = new Set(['post', 'put', 'patch']);
+
+function hasMediaTypes(list) {
+  return Array.isArray(list) && list.length > 0;
+}
+
+module.exports = (given, options, context) => {
+  const errors = [];
+  if (!given) return errors;
+
+  const root = context.document.parserResult.data;
+
+  if (root.swagger) {
+    if (given.responses === undefined) return errors;
+
+    const method = context.path[context.path.length - 1];
+    if (!BODY_ALLOWED_METHODS.has(method)) return errors;
+
+    if (!hasMediaTypes(given.produces) && !hasMediaTypes(root.produces)) {
+      errors.push({
+        message: context.rule.message,
+        path: [...context.path]
+      });
+    }
+
+    return errors;
+  }
+
+  if (given.responses !== undefined) return errors;
+
+  const contentTypes = given.content ? Object.keys(given.content) : [];
+  if (contentTypes.length === 0) {
+    errors.push({
+      message: context.rule.message,
+      path: [...context.path]
+    });
+  }
+
+  return errors;
+};

package/functions/apq-valid-response-schema.js

@@ -1,40 +1,91 @@
+function mergedProperties(schema, visited) {
+  const properties = {};
+  if (!schema || typeof schema !== 'object' || visited.has(schema)) {
+    return properties;
+  }
+  visited.add(schema);
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    Object.assign(properties, schema.properties);
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    for (const subSchema of schema.allOf) {
+      Object.assign(properties, mergedProperties(subSchema, visited));
+    }
+  }
+
+  return properties;
+}
+
 /**
- * @param {object} targetVal
+ * @param {object} given - the 201 response object of a POST operation
  * @param {object} options
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
-module.exports = (targetVal, options, context) => {
-  const errors = [];
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') {
+    return [];
+  }
+
   const dataProperty = (options && options['data-property']) || 'data';
   const VALID_NAMES = [dataProperty, 'error'];
+  const doc = context.document?.data ?? {};
+  const isOAP2 = typeof doc.swagger === 'string';
+  const basePath = context.path || [];
+  const errors = [];
 
-  if (!targetVal || typeof targetVal !== 'object') {
-    return errors;
-  }
+  const checkSchema = (schema, schemaPath) => {
+    if (!schema || typeof schema !== 'object') {
+      errors.push({
+        message: `OAR038: 201 response must define a schema with a '${dataProperty}' or 'error' property.`,
+        path: schemaPath,
+      });
+      return;
+    }
 
-  const path = context.path || [];
-  const responsesIdx = path.lastIndexOf('responses');
-  if (responsesIdx >= 0 && path[responsesIdx + 1] !== '201') {
-    return errors;
-  }
+    const properties = mergedProperties(schema, new WeakSet());
+    const propNames = Object.keys(properties);
 
-  for (const [propName, propValue] of Object.entries(targetVal)) {
-    if (!VALID_NAMES.includes(propName)) {
+    if (propNames.length === 0) {
       errors.push({
-        message: `OAR038: Response property must be named '${dataProperty}' or 'error'. Got '${propName}'.`,
-        path: [...path, propName]
+        message: `OAR038: Response schema must have properties named '${dataProperty}' or 'error'.`,
+        path: schemaPath,
       });
-    } else {
-      const subProps = propValue && propValue.properties;
-      const hasSubProps = subProps && Object.keys(subProps).length > 0;
-      if (!hasSubProps) {
+      return;
+    }
+
+    for (const propName of propNames) {
+      if (!VALID_NAMES.includes(propName)) {
+        errors.push({
+          message: `OAR038: Response property must be named '${dataProperty}' or 'error'. Got '${propName}'.`,
+          path: [...schemaPath, 'properties', propName],
+        });
+        continue;
+      }
+      const subProps = mergedProperties(properties[propName], new WeakSet());
+      if (Object.keys(subProps).length === 0) {
         errors.push({
           message: `OAR038: Property '${propName}' must have at least one sub-property.`,
-          path: [...path, propName]
+          path: [...schemaPath, 'properties', propName],
         });
       }
     }
+  };
+
+  if (isOAP2) {
+    checkSchema(given.schema, [...basePath, 'schema']);
+    return errors;
+  }
+
+  const content = given.content;
+  if (content && typeof content === 'object' && Object.keys(content).length > 0) {
+    for (const [mediaType, mediaObj] of Object.entries(content)) {
+      checkSchema(mediaObj && mediaObj.schema, [...basePath, 'content', mediaType, 'schema']);
+    }
+    return errors;
   }
 
+  checkSchema(given.schema, [...basePath, 'schema']);
   return errors;
 };

package/functions/apq-validate-structure.js

@@ -1,3 +1,24 @@
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function getAt(root, path) {
+  let node = root;
+  for (let i = 0; i < path.length; i += 1) {
+    if (!isPlainObject(node) && !Array.isArray(node)) return undefined;
+    node = node[path[i]];
+  }
+  return node;
+}
+
+function isReachedViaRef(context, fieldName) {
+  const source = context && context.document ? context.document.data : undefined;
+  const path = (context && context.path) || [];
+  if (!isPlainObject(source) && !Array.isArray(source)) return false;
+  const isNestedUnderSchema = fieldName === 'type' && path[path.length - 2] === 'schema';
+  const parameterPath = isNestedUnderSchema ? path.slice(0, -2) : path.slice(0, -1);
+  const raw = getAt(source, parameterPath);
+  return isPlainObject(raw) && typeof raw.$ref === 'string';
+}
+
 /**
  * @param {string} given  - The field value
  * @param {object} options
@@ -8,26 +29,34 @@ module.exports = (given, options, context) => {
 
   const doc = context.document?.data ?? {};
   const isOAP2 = typeof doc.swagger === 'string';
+  const openapi = typeof doc.openapi === 'string' ? doc.openapi : '';
+  const isOAP32 = openapi.indexOf('3.2') === 0;
+  const isNewerOAS = openapi.indexOf('3.1') === 0 || isOAP32;
 
   const VALID_IN_VALUES_OAP2 = ['query', 'header', 'path', 'formData', 'body'];
   const VALID_IN_VALUES_OAP3 = ['path', 'query', 'header', 'cookie'];
-  const VALID_IN_VALUES = isOAP2 ? VALID_IN_VALUES_OAP2 : VALID_IN_VALUES_OAP3;
+  const VALID_IN_VALUES_OAP32 = VALID_IN_VALUES_OAP3.concat(['querystring']);
+  const VALID_IN_VALUES = isOAP2 ? VALID_IN_VALUES_OAP2 : (isOAP32 ? VALID_IN_VALUES_OAP32 : VALID_IN_VALUES_OAP3);
 
   const VALID_SCHEMA_TYPES = ['object', 'string', 'number', 'integer', 'boolean', 'array', 'null'];
 
   const nodePath = context.path || [];
   const fieldName = nodePath[nodePath.length - 1];
 
+  if ((fieldName === 'in' || fieldName === 'type') && isReachedViaRef(context, fieldName)) return [];
+
   if (fieldName === 'in') {
     if (!VALID_IN_VALUES.includes(String(given))) {
-      return [{
+      const issue = {
         message: `in: Expected one of [${VALID_IN_VALUES.map(v => `"${v}"`).join(', ')}]`,
-      }];
+      };
+      if (isOAP2) issue.path = nodePath.slice(0, -1);
+      return [issue];
     }
   }
 
-  if (fieldName === 'type') {
-    if (!VALID_SCHEMA_TYPES.includes(String(given))) {
+  if (fieldName === 'type' && !isNewerOAS) {
+    if (!VALID_SCHEMA_TYPES.includes(given)) {
       return [{
         message: `type: Expected one of [${VALID_SCHEMA_TYPES.map(v => `"${v}"`).join(', ')}]`,
       }];

package/functions/apq-wso2-auth-type-required.js

@@ -0,0 +1,134 @@
+const MESSAGE = 'WSO2 x-scope requires x-auth-type definition';
+
+const VERBS_V2 = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'];
+const VERBS_V3 = VERBS_V2.concat(['trace']);
+const VERBS_V32 = VERBS_V3.concat(['query']);
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function documentVersion(root) {
+  if (Object.prototype.hasOwnProperty.call(root, 'swagger')) return 'v2';
+  const openapi = root.openapi;
+  if (typeof openapi === 'string') {
+    if (openapi.indexOf('3.2') === 0) return 'v32';
+    if (openapi.indexOf('3.1') === 0) return 'v31';
+  }
+  return 'v3';
+}
+
+function surfaceFor(version) {
+  return {
+    verbs: version === 'v32' ? VERBS_V32 : (version === 'v2' ? VERBS_V2 : VERBS_V3),
+    components: version !== 'v2',
+    callbacks: version !== 'v2',
+    webhooks: version === 'v31' || version === 'v32',
+    pathItems: version === 'v31' || version === 'v32',
+    additionalOperations: version === 'v32',
+  };
+}
+
+function collectOperations(root, surface) {
+  const operations = [];
+
+  const visitOperation = (op, path) => {
+    if (isPlainObject(op)) operations.push({ op, path });
+  };
+
+  const visitOperationWithCallbacks = (op, path) => {
+    visitOperation(op, path);
+    if (!surface.callbacks || !isPlainObject(op) || !isPlainObject(op.callbacks)) return;
+    Object.keys(op.callbacks).forEach((expressionKey) => {
+      if (expressionKey.charAt(0) === 'x') return;
+      const callback = op.callbacks[expressionKey];
+      if (!isPlainObject(callback)) return;
+      Object.keys(callback).forEach((pathKey) => {
+        if (pathKey.charAt(0) === 'x') return;
+        // eslint-disable-next-line no-use-before-define
+        visitPathItem(callback[pathKey], path.concat(['callbacks', expressionKey, pathKey]));
+      });
+    });
+  };
+
+  const visitPathItem = (pathItem, path) => {
+    if (!isPlainObject(pathItem)) return;
+    surface.verbs.forEach((verb) => {
+      if (Object.prototype.hasOwnProperty.call(pathItem, verb)) {
+        visitOperationWithCallbacks(pathItem[verb], path.concat([verb]));
+      }
+    });
+    if (surface.additionalOperations && isPlainObject(pathItem.additionalOperations)) {
+      Object.keys(pathItem.additionalOperations).forEach((method) => {
+        visitOperationWithCallbacks(pathItem.additionalOperations[method], path.concat(['additionalOperations', method]));
+      });
+    }
+  };
+
+  if (isPlainObject(root.paths)) {
+    Object.keys(root.paths).forEach((pathKey) => {
+      if (pathKey.charAt(0) !== '/') return;
+      visitPathItem(root.paths[pathKey], ['paths', pathKey]);
+    });
+  }
+
+  if (surface.webhooks && isPlainObject(root.webhooks)) {
+    Object.keys(root.webhooks).forEach((name) => {
+      visitPathItem(root.webhooks[name], ['webhooks', name]);
+    });
+  }
+
+  if (surface.components && isPlainObject(root.components)) {
+    const components = root.components;
+    if (surface.callbacks && isPlainObject(components.callbacks)) {
+      Object.keys(components.callbacks).forEach((name) => {
+        const callback = components.callbacks[name];
+        if (!isPlainObject(callback)) return;
+        Object.keys(callback).forEach((pathKey) => {
+          if (pathKey.charAt(0) === 'x') return;
+          visitPathItem(callback[pathKey], ['components', 'callbacks', name, pathKey]);
+        });
+      });
+    }
+    if (surface.pathItems && isPlainObject(components.pathItems)) {
+      Object.keys(components.pathItems).forEach((name) => {
+        visitPathItem(components.pathItems[name], ['components', 'pathItems', name]);
+      });
+    }
+    if (surface.webhooks && isPlainObject(components.webhooks)) {
+      Object.keys(components.webhooks).forEach((name) => {
+        visitPathItem(components.webhooks[name], ['components', 'webhooks', name]);
+      });
+    }
+  }
+
+  return operations;
+}
+
+function issuePrefix(context) {
+  const name = (context && context.rule && context.rule.name) || '';
+  const code = name.indexOf(':') === -1 ? name : name.split(':').pop();
+  return code ? `${code}: ` : '';
+}
+
+/**
+ * @param {object} given the whole raw document, since the rule is anchored with `given: "$"`
+ * @param {null} _options OAR041 has no rule properties on either engine
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ * @returns {Array<{message: string, path: Array<string|number>}>}
+ */
+module.exports = (given, _options, context) => {
+  if (!isPlainObject(given)) return [];
+
+  const version = documentVersion(given);
+  const surface = surfaceFor(version);
+  const prefix = issuePrefix(context);
+  const results = [];
+
+  collectOperations(given, surface).forEach(({ op, path }) => {
+    if (!Object.prototype.hasOwnProperty.call(op, 'x-scope')) return;
+    if (Object.prototype.hasOwnProperty.call(op, 'x-auth-type')) return;
+
+    results.push({ message: `${prefix}${MESSAGE}`, path: path.concat(['x-scope']) });
+  });
+
+  return results;
+};