api-quality-spectral-ruleset 1.1.1 → 1.2.0

package/functions/apq-check-ambiguous-path.js

@@ -0,0 +1,52 @@
+/**
+ * Validates that URL path segments use clear, unambiguous names
+ * @param {string} given - The path key (e.g. "/users/{id}/items")
+ * @param {object} options - Function options
+ * @param {string} options.ambiguous-words - Comma-separated list of ambiguous words
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const results = [];
+
+  if (typeof given !== 'string') {
+    return results;
+  }
+
+  // Default ambiguous words (from the original regex)
+  const defaultAmbiguousWords = [
+    'elements', 'instances', 'resources', 'values', 'terms', 'objects', 'items'
+  ];
+
+  // Parse custom ambiguous words from options if provided
+  let ambiguousWords = defaultAmbiguousWords;
+  if (options && options['ambiguous-words']) {
+    ambiguousWords = options['ambiguous-words']
+      .split(',')
+      .map(w => w.trim().toLowerCase())
+      .filter(Boolean);
+  }
+
+  // Split path into segments and filter out parameters
+  const segments = given
+    .split('/')
+    .filter(segment => {
+      // Keep only static segments (not empty, not {param})
+      return segment.length > 0 && !segment.startsWith('{');
+    });
+
+  // Check each segment for ambiguous words
+  for (const segment of segments) {
+    const lowerSegment = segment.toLowerCase();
+    for (const word of ambiguousWords) {
+      if (lowerSegment.includes(word)) {
+        results.push({
+          message: `${context.rule.message || 'OAR032'}: Path segment '${segment}' is ambiguous. Avoid using words like '${word}' in resource names.`,
+          path: context.path
+        });
+        break; // Report only once per segment
+      }
+    }
+  }
+
+  return results;
+};

package/functions/apq-check-examples-coverage.js

@@ -39,6 +39,18 @@ module.exports = (given, options, context) => {
       return checkSchema(schema.items);
     }
 
+    if (schema.allOf && Array.isArray(schema.allOf)) {
+      return schema.allOf.some(subSchema => checkSchema(subSchema));
+    }
+
+    if (schema.oneOf && Array.isArray(schema.oneOf)) {
+      return schema.oneOf.some(subSchema => checkSchema(subSchema));
+    }
+
+    if (schema.anyOf && Array.isArray(schema.anyOf)) {
+      return schema.anyOf.some(subSchema => checkSchema(subSchema));
+    }
+
     return false;
   };
 

package/functions/apq-compare-insensitive.js

@@ -1,11 +1,13 @@
 /**
- * @param {object} given                   
- * @param {object} options                 
- * @param {string} options.property        
- * @param {string} options.equalTo         
- * @param {string} options.result          
- * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context    
- *                                         
+ * Enhanced semantic text comparison function
+ * Detects both exact matches and semantic similarity
+ * @param {object} given
+ * @param {object} options
+ * @param {string} options.property
+ * @param {string} options.equalTo
+ * @param {string} options.result
+ * @param {number} options.threshold       - Similarity threshold (0.0-1.0), default 0.6
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
   const errors = [];
@@ -16,18 +18,113 @@ module.exports = (given, options, context) => {
   const propA = given[options.property];
   const propB = given[options.equalTo];
 
-  if (
-    typeof propA === 'string' &&
-    typeof propB === 'string' &&
-    options.result === 'falsy' &&
-    propA.trim().toUpperCase() === propB.trim().toUpperCase()
-  ) {
+  if (typeof propA !== 'string' || typeof propB !== 'string') {
+    return errors;
+  }
+
+  if (options.result !== 'falsy') {
+    return errors;
+  }
+
+  const threshold = options.threshold || 0.6;
+
+  // Exact match (case-insensitive)
+  if (propA.trim().toUpperCase() === propB.trim().toUpperCase()) {
     errors.push({
       message: context.rule.message,
       path: [...context.path, options.property]
     });
+    return errors;
+  }
+
+  // Semantic similarity check
+  const similarity = calculateSimilarity(propA, propB);
+  if (similarity >= threshold) {
+    errors.push({
+      message: `${context.rule.message} (${Math.round(similarity * 100)}% similar)`,
+      path: [...context.path, options.property]
+    });
   }
 
   return errors;
 };
 
+/**
+ * Calculate semantic similarity between two strings
+ * Uses token overlap and cosine similarity
+ */
+function calculateSimilarity(str1, str2) {
+  const tokens1 = tokenize(str1);
+  const tokens2 = tokenize(str2);
+
+  if (tokens1.length === 0 || tokens2.length === 0) {
+    return 0;
+  }
+
+  // Calculate Jaccard similarity (token overlap)
+  const intersection = new Set([...tokens1].filter(x => tokens2.includes(x)));
+  const union = new Set([...tokens1, ...tokens2]);
+  const jaccardSimilarity = intersection.size / union.size;
+
+  // Calculate word order similarity
+  const order1 = tokens1.join(' ');
+  const order2 = tokens2.join(' ');
+  const levenshteinDist = levenshteinDistance(order1, order2);
+  const maxLen = Math.max(order1.length, order2.length);
+  const orderSimilarity = maxLen === 0 ? 0 : 1 - levenshteinDist / maxLen;
+
+  // Weighted average
+  return jaccardSimilarity * 0.6 + orderSimilarity * 0.4;
+}
+
+/**
+ * Tokenize string into meaningful words with stemming
+ */
+function tokenize(str) {
+  return str
+    .toLowerCase()
+    .replace(/[^\w\s]/g, '')
+    .split(/\s+/)
+    .filter(token => token.length > 2) // Ignore very short words
+    .map(token => stem(token)) // Apply stemming
+    .sort();
+}
+
+/**
+ * Simple word stemming (removes common suffixes)
+ */
+function stem(word) {
+  // Remove common verb/noun suffixes
+  return word
+    .replace(/s$/, '')           // plural
+    .replace(/ed$/, '')          // past tense
+    .replace(/ing$/, '')         // continuous
+    .replace(/er$/, '')          // agent
+    .replace(/est$/, '');        // superlative
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(str1, str2) {
+  const len1 = str1.length;
+  const len2 = str2.length;
+  const matrix = Array(len2 + 1).fill(null).map(() => Array(len1 + 1).fill(0));
+
+  for (let i = 0; i <= len1; i++) matrix[0][i] = i;
+  for (let j = 0; j <= len2; j++) matrix[j][0] = j;
+
+  for (let j = 1; j <= len2; j++) {
+    for (let i = 1; i <= len1; i++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      matrix[j][i] = Math.min(
+        matrix[j][i - 1] + 1,
+        matrix[j - 1][i] + 1,
+        matrix[j - 1][i - 1] + cost
+      );
+    }
+  }
+
+  return matrix[len2][len1];
+}
+

package/functions/apq-has-filter-query-param.js

@@ -0,0 +1,26 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') {
+    return [];
+  }
+
+  const params = given.parameters;
+
+  if (!params || !Array.isArray(params)) {
+    return [{ message: context.rule.message }];
+  }
+
+  const hasFilter = params.some(
+    p => p && !p.$ref && p.name === '$filter' && p.in === 'query'
+  );
+
+  if (!hasFilter) {
+    return [{ message: context.rule.message }];
+  }
+
+  return [];
+};

package/functions/apq-paged-response-check.js

@@ -0,0 +1,124 @@
+module.exports = (schema, options = {}, context) => {
+  const results = [];
+
+  if (!schema || typeof schema !== 'object') {
+    return results;
+  }
+
+  // Parse paging schema from options
+  let pagingSchema = {};
+  try {
+    const pagingSchemaStr = options['paging-schema'] || defaultPagingSchema;
+    pagingSchema = typeof pagingSchemaStr === 'string'
+      ? JSON.parse(pagingSchemaStr)
+      : pagingSchemaStr;
+  } catch (err) {
+    return [{
+      message: `${context.rule.name.split(':').pop()}: Invalid paging-schema configuration: ${err.message}`,
+      path: context.path,
+    }];
+  }
+
+  const pagingPropertyName = pagingSchema.pagingPropertyName || 'paging';
+  const requiredFields = pagingSchema.required || [];
+  const properties = pagingSchema.properties || {};
+
+  // Check if schema doesn't have properties at all - skip validation
+  if (!schema.properties) {
+    return results;
+  }
+
+  // Check if schema has the paging property
+  if (!schema.properties[pagingPropertyName]) {
+    // Only flag if schema looks like it should have paging (has data/items/results arrays)
+    const hasArrayProperty = Object.values(schema.properties || {}).some(
+      prop => prop && prop.type === 'array'
+    );
+
+    if (hasArrayProperty) {
+      results.push({
+        message: `${context.rule.name.split(':').pop()}: Response must include '${pagingPropertyName}' property for pagination`,
+        path: context.path,
+      });
+    }
+    return results;
+  }
+
+  const pagingObj = schema.properties[pagingPropertyName];
+
+  // Validate paging object structure
+  if (!pagingObj.properties) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: '${pagingPropertyName}' must be an object with required properties`,
+      path: [...context.path, 'properties', pagingPropertyName],
+    });
+    return results;
+  }
+
+  // Check required fields
+  const missingFields = [];
+  for (const requiredField of requiredFields) {
+    if (!pagingObj.properties[requiredField]) {
+      missingFields.push(requiredField);
+    }
+  }
+
+  if (missingFields.length > 0) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: Paging object must include required fields: ${missingFields.join(', ')}`,
+      path: [...context.path, 'properties', pagingPropertyName, 'properties'],
+    });
+  }
+
+  // Special validation for links object if it's required
+  if (requiredFields.includes('links') && pagingObj.properties.links) {
+    const linksObj = pagingObj.properties.links;
+    if (linksObj.properties) {
+      const requiredLinks = ['self', 'previous', 'next']; // From default schema
+      const linksRequired = linksObj.required || [];
+
+      for (const requiredLink of requiredLinks) {
+        if (!linksObj.properties[requiredLink]) {
+          results.push({
+            message: `${context.rule.name.split(':').pop()}: Links object must include '${requiredLink}' property`,
+            path: [...context.path, 'properties', pagingPropertyName, 'properties', 'links', 'properties'],
+          });
+        }
+      }
+
+      // Check if links has required array
+      if (!linksRequired.includes('self') || !linksRequired.includes('previous') || !linksRequired.includes('next')) {
+        results.push({
+          message: `${context.rule.name.split(':').pop()}: Links object must require 'self', 'previous', and 'next'`,
+          path: [...context.path, 'properties', pagingPropertyName, 'properties', 'links'],
+        });
+      }
+    }
+  }
+
+  return results;
+};
+
+// Default paging schema matching Java implementation
+const defaultPagingSchema = JSON.stringify({
+  type: 'object',
+  properties: {
+    numPages: { type: 'integer' },
+    total: { type: 'integer' },
+    start: { type: 'integer' },
+    limit: { type: 'integer' },
+    links: {
+      type: 'object',
+      properties: {
+        next: { type: 'object', properties: { href: { type: 'string' } } },
+        previous: { type: 'object', properties: { href: { type: 'string' } } },
+        last: { type: 'object', properties: { href: { type: 'string' } } },
+        self: { type: 'object', properties: { href: { type: 'string' } } },
+        first: { type: 'object', properties: { href: { type: 'string' } } },
+      },
+      required: ['self', 'previous', 'next'],
+    },
+  },
+  required: ['start', 'limit', 'links'],
+  pagingPropertyName: 'paging',
+});

package/functions/apq-password-format.js

@@ -0,0 +1,35 @@
+/**
+ * Validates that properties intended for password storage use format: password
+ * @param {object} given - The schema properties object
+ * @param {object} options - Function options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const results = [];
+
+  if (!given || typeof given !== 'object') {
+    return results;
+  }
+
+  // Check each property in the schema
+  Object.entries(given).forEach(([propName, propSchema]) => {
+    if (!propSchema || typeof propSchema !== 'object') {
+      return;
+    }
+
+    // Check if this is a password-related field (name contains "password")
+    const isPasswordField = propName.toLowerCase().includes('password');
+
+    if (isPasswordField && propSchema.type === 'string') {
+      // Password fields must have format: password
+      if (propSchema.format !== 'password') {
+        results.push({
+          message: context.rule.message || 'OAR081: Password fields should use format: password',
+          path: [...context.path, propName, 'format']
+        });
+      }
+    }
+  });
+
+  return results;
+};

package/functions/apq-path-depth.js

@@ -0,0 +1,20 @@
+/**
+ * @param {string} targetVal
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  const maxDepth = options.maxDepth ?? 3
+  const ignore = options.ignoreSegments ?? []
+
+  const segments = targetVal
+    .split('/')
+    .filter(Boolean)
+    .filter(segment => !ignore.includes(segment))
+
+  if (segments.length > maxDepth) {
+    return [
+      { message: context.rule.message }
+    ]
+  }
+}

package/functions/apq-path-param-query-conflict.js

@@ -0,0 +1,54 @@
+/**
+ * Validates that path parameters don't appear as query parameters
+ * This prevents ambiguity and design issues
+ *
+ * @param {object} given - The paths object
+ * @param {object} options - Function options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const errors = [];
+
+  if (!given || typeof given !== 'object') {
+    return errors;
+  }
+
+  const httpMethods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
+
+  for (const [pathKey, pathItem] of Object.entries(given)) {
+    if (!pathItem || typeof pathItem !== 'object') {
+      continue;
+    }
+
+    for (const [operationKey, operation] of Object.entries(pathItem)) {
+      if (!operation || typeof operation !== 'object' ||
+          !httpMethods.includes(operationKey)) {
+        continue;
+      }
+
+      const parameters = operation.parameters || [];
+
+      if (!Array.isArray(parameters)) {
+        continue;
+      }
+
+      const hasPathOrQueryParams = parameters.some(
+        param => param && (param.in === 'path' || param.in === 'query')
+      );
+
+      if (!hasPathOrQueryParams) {
+        continue;
+      }
+
+      const responses = operation.responses || {};
+      if (!responses['400']) {
+        errors.push({
+          message: `OAR069: Any param in PATH or QUERY, should have bad request (400) response.`,
+          path: [...context.path, pathKey, operationKey, 'responses']
+        });
+      }
+    }
+  }
+
+  return errors;
+};

package/functions/apq-resources-by-verb.js

@@ -29,7 +29,7 @@ const DEFAULT_ALLOWED_PATTERNS = `
 ;delete:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
 `;
 
-const SUPPORTED_VERBS = ['get', 'post', 'put', 'patch', 'delete'];
+const SUPPORTED_VERBS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
 const CONFIG_ERROR_PREFIX = 'OAR018:';
 
 const parseAllowedPatterns = (patterns) => {

package/functions/apq-response-headers.js

@@ -41,7 +41,7 @@ module.exports = (responseNode, options = {}, context) => {
   const path = context.path?.find(p => typeof p === 'string' && p.startsWith('/'));
   const responseCode = context.path?.[context.path.length - 1];
 
-  if (path && pathExclusions.includes(path)) {
+  if (path && pathExclusions.some(ex => path === ex || path.startsWith(ex + '/'))) {
     return [];
   }
 
@@ -85,7 +85,8 @@ module.exports = (responseNode, options = {}, context) => {
     const forbidden = headerNames.filter(h => !allowedHeaders.includes(h));
     if (forbidden.length > 0) {
       results.push({
-        message: `${ruleCode}: Header not allowed`,
+        message: `${ruleCode}: Headers [${forbidden.join(', ')}] are not allowed`,
+        path: [...context.path, 'headers', forbidden[0]],
       });
     }
   }

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

@@ -0,0 +1,43 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+
+const NO_BODY_CODES = new Set(['204']);
+
+module.exports = (given, options, context) => {
+  const errors = [];
+  if (!given) return errors;
+
+  const root = context.document.parserResult.data;
+
+  if (root.swagger) {
+    const produces = given.produces ?? root.produces;
+
+    if (!produces || !Array.isArray(produces) || !produces.includes('application/json')) {
+      errors.push({
+        message: context.rule.message,
+        path: [...context.path]
+      });
+    }
+
+    return errors;
+  }
+
+  const responses = given.responses;
+  if (!responses) return errors;
+
+  for (const [statusCode, response] of Object.entries(responses)) {
+    if (NO_BODY_CODES.has(statusCode)) continue;
+
+    if (!response?.content?.['application/json']) {
+      errors.push({
+        message: context.rule.message,
+        path: [...context.path, 'responses', statusCode]
+      });
+    }
+  }
+
+  return errors;
+};

package/functions/apq-security-required-response.js

@@ -0,0 +1,46 @@
+/**
+ * Validates that operations with security defined include a 401 Unauthorized response
+ * @param {object} given - The operation node
+ * @param {object} options - Function options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const results = [];
+
+  if (!given || typeof given !== 'object') {
+    return results;
+  }
+
+  const responses = given.responses;
+  if (!responses || typeof responses !== 'object') {
+    return results;
+  }
+
+  // Check if this operation has security defined
+  const operationHasSecurity = given.security &&
+    Array.isArray(given.security) &&
+    given.security.length > 0;
+
+  // Check if there's global security in the document
+  let globalHasSecurity = false;
+  try {
+    const rootSecurity = context.document?.parserResult?.data?.security;
+    globalHasSecurity = rootSecurity &&
+      Array.isArray(rootSecurity) &&
+      rootSecurity.length > 0;
+  } catch (e) {
+    // Ignore errors accessing root security
+  }
+
+  // Only require 401 if security is defined (operation-level or global)
+  if (operationHasSecurity || globalHasSecurity) {
+    if (!responses['401']) {
+      results.push({
+        message: context.rule.message || 'OAR035: Response code 401 must be defined for operations with security schemes defined.',
+        path: [...context.path, 'responses']
+      });
+    }
+  }
+
+  return results;
+};

package/functions/apq-standard-response-codes.js

@@ -22,7 +22,10 @@ module.exports = function apqStandardResponseCodes(given, options, context) {
 
   const exclusions = options?.['resources-exclusions'] || [];
   if (exclusions.some(ex => {
-    const [exVerb, exPath] = ex.split(':');
+    const colonIdx = ex.indexOf(':');
+    if (colonIdx === -1) return false;
+    const exVerb = ex.slice(0, colonIdx);
+    const exPath = ex.slice(colonIdx + 1);
     return exVerb.toLowerCase() === verb.toLowerCase() && new RegExp(`^${exPath}$`).test(resourcePath);
   })) return results;
 

package/functions/apq-status-endpoint-check.js

@@ -0,0 +1,32 @@
+module.exports = (paths, options = {}, context) => {
+  const results = [];
+
+  if (!paths || typeof paths !== 'object') {
+    return results;
+  }
+
+  // Get configuration options
+  const statusEndpoint = (options['status-endpoint'] || '/status').trim();
+  const method = (options['method'] || 'get').toLowerCase().trim();
+
+  // Check if the endpoint exists
+  if (!paths[statusEndpoint]) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: The status endpoint '${statusEndpoint}' must be declared`,
+      path: context.path,
+    });
+    return results;
+  }
+
+  const endpointNode = paths[statusEndpoint];
+
+  // Check if the configured method exists
+  if (!endpointNode[method]) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: The status endpoint '${statusEndpoint}' must support the '${method.toUpperCase()}' method`,
+      path: [...context.path, statusEndpoint],
+    });
+  }
+
+  return results;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [

package/functions/apq-default-value.js

@@ -1,23 +0,0 @@
-/**
- * @param {object} given
- * @param {object} options
- * @param {string} options.type
- * @param {string} options.match
- * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
- */
-module.exports = (given, options, context) => {
-    const errors = [];
-    if (!given) return errors;
-
-    if (!given.type || given.type.toString() !== options.type.toString()) {
-      errors.push({
-          message: context.rule.message,
-      });
-    } else if (!given.default || given.default.toString() !== options.match.toString()) {
-      errors.push({
-          message: context.rule.message,
-      });
-    }
-
-    return errors;
-}