api-quality-spectral-ruleset 1.0.0

package/functions/apq-alternate-paths.js

@@ -0,0 +1,35 @@
+
+const isVariable = (part) => {
+  return (part.startsWith('{') && part.endsWith('}'));
+}
+
+module.exports = (given, { except }, context) => {
+  const result = [];
+  const paths = given || [];
+  if (paths.length === 0) return result;
+
+  const parts = paths.substr(1).split('/');
+  let previousIsVar = isVariable(parts.shift());
+  if (previousIsVar) {
+    return [{
+      message: context.rule.message,
+    }];
+  }
+
+  for (const part of parts) {
+    if (except && except.includes(part)) {
+      previousIsVar = true;
+      continue;
+    }
+
+    const currentIsVariable = isVariable(part);
+    if (currentIsVariable === previousIsVar) {
+      return [{
+        message: context.rule.message,
+      }];
+    }
+    previousIsVar = currentIsVariable;
+  }
+
+  return result;
+};

package/functions/apq-at-most-one-body-parameter.js

@@ -0,0 +1,24 @@
+/**
+ * @param {string} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (parameters, options, context) => {
+  if (!parameters || !Array.isArray(parameters) || parameters.length === 0) {
+    return [];
+  }
+
+  const bodyParams = parameters.filter(param => {
+    return param && typeof param === 'object' && param.in === 'body';
+  });
+
+  if (bodyParams.length > 1) {
+    return [
+      {
+        message: context.rule.message,
+      }
+    ];
+  }
+
+  return [];
+};

package/functions/apq-compare-insensitive.js

@@ -0,0 +1,33 @@
+/**
+ * @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    
+ *                                         
+ */
+module.exports = (given, options, context) => {
+  const errors = [];
+  if (!given) {
+    return errors;
+  }
+
+  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()
+  ) {
+    errors.push({
+      message: context.rule.message,
+      path: [...context.path, options.property]
+    });
+  }
+
+  return errors;
+};
+

package/functions/apq-custom-schema.js

@@ -0,0 +1,88 @@
+// options:
+//   except: 'array<string>'
+//   schema: object
+
+function DeepCompare() {
+  var i, l, leftChain, rightChain;
+
+  function Objects(x, y, required = []) {
+    let p;
+
+    // Quick checking of one object being a subset of another.
+    // todo: cache the structure of arguments[0] for performance
+    for (p in y) {
+      if (y.hasOwnProperty(p) !== x.hasOwnProperty(p)) {
+        if (required.includes(p)) {
+          return false;
+        }
+      } else if (typeof y[p] !== typeof x[p]) {
+        return false;
+      }
+    }
+
+    for (p in x) {
+      if (y.hasOwnProperty(p) !== x.hasOwnProperty(p)) {
+        if (required.includes(p)) {
+          return false;
+        }
+        continue;
+      } else if (typeof y[p] !== typeof x[p]) {
+        return false;
+      }
+
+      switch (typeof x[p]) {
+        case "object":
+        case "function":
+          leftChain.push(x);
+          rightChain.push(y);
+
+          if (!Objects(x[p], y[p], x[p].required || required)) {
+            return false;
+          }
+
+          leftChain.pop();
+          rightChain.pop();
+          break;
+
+        default:
+          if (x[p] !== y[p]) {
+            return false;
+          }
+          break;
+      }
+    }
+
+    return true;
+  }
+
+  for (i = 1, l = arguments.length; i < l; i++) {
+    leftChain = []; //Todo: this can be cached
+    rightChain = [];
+
+    if (!Objects(arguments[0], arguments[i], arguments[0].required || [])) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * @param {Array<string>} given
+ * @param {object} options
+ * @param {Array<string>} options.except
+ * @param {object} options.schema
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const result = [];
+  const paths = given || [];
+  if (paths.length === 0) return result;
+  if (options.except.includes(String(context.path[1]))) return result;
+
+  if (DeepCompare(options.schema, given)) return result;
+
+  return [{
+    message: context.rule.message,
+  }];
+};

package/functions/apq-default-value.js

@@ -0,0 +1,23 @@
+/**
+ * @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;
+}

package/functions/apq-naming-convention.js

@@ -0,0 +1,21 @@
+const { pattern } = require("@stoplight/spectral-functions");
+
+const patterns = {
+    kebabCase: /^(\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$/,
+    camelCase: /^[a-z]+([A-Z][a-z0-9]+)*$/,
+    snakeCase: /^[a-z]+(_[a-z0-9]+)*$/,
+    pascalCase: /^[A-Z]+([A-Z][a-z0-9]+)*$/
+};
+
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {string} options.pattern
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+    const errors = [];
+    if (!given) return errors;
+
+    return pattern(given, { match: patterns[options.pattern] }, context);
+}

package/functions/apq-parameter-naming-convention.js

@@ -0,0 +1,76 @@
+const NAMING_REGEX = {
+  "snake_case": /^[a-z0-9_$]*$/,
+  "kebab-case": /^[a-z0-9-]*$/,
+  "camelCase": /^[a-z]+([A-Z][a-z]+)*([A-Z])?$/,
+  "UpperCamelCase": /^[A-Z][a-z]+(?:[A-Z][a-z]+)*$/
+};
+
+const NAME_EXCEPTIONS = new Set([
+  "$init", "$start", "$limit", "$total", "$expand", "$orderby", "$select", "$exclude", "$filter"
+]);
+
+const PARAM_REGEX = /\{([^}{]*)\}/g;
+
+/**
+ * @param {string} given
+ * @param {object} options
+ * @param {string} options.namingConvention
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given) return [];
+
+  const convention = options.namingConvention || "snake_case";
+  const regex = NAMING_REGEX[convention];
+
+  if (!regex) {
+    throw new Error(
+      `OAR012: Unknown naming convention "${convention}". ` +
+      `Allowed values: ${Object.keys(NAMING_REGEX).join(", ")}`
+    );
+  }
+
+  if (NAME_EXCEPTIONS.has(given)) {
+    return [];
+  }
+
+  let name = given;
+
+  // Strip parameter names
+  name = name.replace(PARAM_REGEX, (_, match) => match); // Keep only the parameter name without braces
+
+  switch (convention) {
+    case "camelCase":
+    case "UpperCamelCase":
+      name = name.replace(/\//g, "");
+      if (name.includes("_") || name.includes("-")) {
+        return [
+          {
+            message: `OAR012: "${given}" must follow ${convention}`,
+            path: context.path
+          }
+        ];
+      }
+      break;
+
+    case "kebab-case":
+      name = name.replace(/\//g, "-");
+      break;
+
+    case "snake_case":
+    default:
+      name = name.replace(/\//g, "_");
+      break;
+  }
+
+  if (!regex.test(name)) {
+    return [
+      {
+        message: `OAR012: "${given}" must follow ${convention}`,
+        path: context.path
+      }
+    ];
+  }
+
+  return [];
+};

package/functions/apq-properties-schema-format.js

@@ -0,0 +1,29 @@
+// Check that format is valid for a schema type.
+
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {Array<string>} options.formats
+ * @param {Array<string>} options.properties
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = function checkTypeAndFormat(given, options, context) {
+  if (given === null || typeof given !== "object") {
+    return [];
+  }
+
+  const errors = [];
+  const path = context.path || [];
+  const name = path.slice(-1)[0].toString();
+
+  if (options.properties.includes(name)) {
+    if (!given.format || !options.formats.includes(given.format)) {
+      errors.push({
+        message: context.rule.message,
+        path: [...path, name]
+      });
+    }
+  }
+
+  return errors;
+};

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

@@ -0,0 +1,117 @@
+const DEFAULT_ALLOWED_PATTERNS = `
+;get:^/[^/{}]+$
+;get:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+$
+;get:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+$
+;get:^/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;get:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;get:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+
+;post:^/[^/{}]+$
+;post:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+$
+;post:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+$
+;post:^/[^/{}]+/get$
+;post:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/get$
+;post:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/get$
+;post:^/[^/{}]+/delete$
+;post:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/delete$
+;post:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/delete$
+
+;put:^/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;put:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;put:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+
+;patch:^/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;patch:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;patch:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+
+;delete:^/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;delete:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+;delete:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
+`;
+
+const SUPPORTED_VERBS = ['get', 'post', 'put', 'patch', 'delete'];
+const CONFIG_ERROR_PREFIX = 'OAR018:';
+
+const parseAllowedPatterns = (patterns) => {
+  if (typeof patterns !== 'string') {
+    throw new Error(
+      `${CONFIG_ERROR_PREFIX} allowed-resources-paths must be a string`
+    );
+  }
+
+  return patterns
+    .split(';')
+    .map(p => p.trim())
+    .filter(Boolean)
+    .map(entry => {
+      const idx = entry.indexOf(':');
+
+      if (idx === -1) {
+        throw new Error(
+          `${CONFIG_ERROR_PREFIX} Invalid entry "${entry}". Expected format "<verb>:<regex>"`
+        );
+      }
+
+      const verb = entry.slice(0, idx).toLowerCase();
+      const regexSource = entry.slice(idx + 1);
+
+      if (!SUPPORTED_VERBS.includes(verb)) {
+        throw new Error(
+          `${CONFIG_ERROR_PREFIX} Unsupported HTTP verb "${verb}" in "${entry}"`
+        );
+      }
+
+      try {
+        return {
+          verb,
+          regex: new RegExp(regexSource),
+        };
+      } catch (err) {
+        throw new Error(
+          `${CONFIG_ERROR_PREFIX} Invalid regex for verb "${verb}": ${regexSource}. ${err.message}`
+        );
+      }
+    });
+};
+
+module.exports = (given, functionOptions = {}, context) => {
+  const results = [];
+  if (!given || typeof given !== 'object') return results;
+
+  let allowedPatterns;
+
+  try {
+    const patterns = functionOptions['allowed-resources-paths']?.trim()
+        ? functionOptions['allowed-resources-paths']
+        : DEFAULT_ALLOWED_PATTERNS;
+
+    allowedPatterns = parseAllowedPatterns(patterns);
+  } catch (error) {
+    return [{
+      message: error.message,
+      path: context.path,
+    }];
+  }
+
+  Object.entries(given).forEach(([path, operations]) => {
+    Object.keys(operations || {}).forEach(verb => {
+      const verbLower = verb.toLowerCase();
+      if (!SUPPORTED_VERBS.includes(verbLower)) return;
+
+      const isAllowed = allowedPatterns.some(p =>
+        p.verb === verbLower && p.regex.test(path)
+      );
+
+      if (!isAllowed) {
+        results.push({
+          message: context.rule.message
+            .replace('{{path}}', path)
+            .replace('{{verb}}', verbLower.toUpperCase()),
+          path: [...context.path, path, verb],
+        });
+      }
+    });
+  });
+
+  return results;
+};

package/functions/apq-responses.js

@@ -0,0 +1,26 @@
+
+module.exports = (given, options, context) => {
+  const result = [];
+  if (!given) return result;
+
+  if (options.verbs !== '*' && !Object.keys(given).some(key => options.verbs.includes(key))) {
+    return result;
+  }
+
+  Object.keys(given).forEach(element => {
+    const verb = given[element];
+    if (!verb.responses) return;
+    if (options.parameters && !verb.parameters) return;
+    if (options.parameters && !verb.parameters.some(p => options.parameters.includes(p.in))) return;
+
+    if (Object.keys(verb.responses).some(response => options.responses.includes(response))) return;
+
+    const path = context.path || [];
+    result.push({
+      message: context.rule.message,
+      path: [...path, element]
+    });
+  });
+
+  return result;
+};

package/functions/apq-schema-format.js

@@ -0,0 +1,98 @@
+// Check that format is valid for a schema type.
+
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {object} options.formats
+ * @param {Array<string>} options.formats.string
+ * @param {Array<string>} options.formats.number
+ * @param {Array<string>} options.formats.integer
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = function checkTypeAndFormat(given, options, context) {
+  if (given === null || typeof given !== "object") {
+    return [];
+  }
+
+  const errors = [];
+  const path = context.path || [];
+
+  if (given.type === "string" && options.formats.string) {
+    if (given.format) {
+      if (!options.formats.string.includes(given.format)) {
+        errors.push({
+          message: `Schema with type string has unrecognized format: ${given.format}`,
+          path: [...path, "format"]
+        });
+      }
+    }
+  } else if (given.type === "integer" && options.formats.integer) {
+    if (given.format) {
+      if (!options.formats.integer.includes(given.format)) {
+        errors.push({
+          message: `Schema with type integer has unrecognized format: ${given.format}`,
+          path: [...path, "format"]
+        });
+      }
+    } else {
+      errors.push({
+        message: "Schema with type integer should specify format",
+        path
+      });
+    }
+  } else if (given.type === "number" && options.formats.number) {
+    if (given.format) {
+      if (!options.formats.number.includes(given.format)) {
+        errors.push({
+          message: `Schema with type number has unrecognized format: ${given.format}`,
+          path: [...path, "format"]
+        });
+      }
+    } else {
+      errors.push({
+        message: "Schema with type number should specify format",
+        path
+      });
+    }
+  } else if (given.type === "boolean") {
+    if (given.format) {
+      errors.push({
+        message: "Schema with type boolean should not specify format",
+        path: [...path, "format"]
+      });
+    }
+  } else if (given.properties && typeof given.properties === "object") {
+    // eslint-disable-next-line no-restricted-syntax
+    for (const [key, value] of Object.entries(given.properties)) {
+      errors.push(...checkTypeAndFormat(value, options, {
+        path: [...path, "properties", key],
+        document: context.document,
+        documentInventory: context.documentInventory,
+        rule: context.rule
+      }));
+    }
+  }
+
+  if (given.type === "array") {
+    errors.push(...checkTypeAndFormat(given.items, options, {
+      path: [...path, "items"],
+      document: context.document,
+      documentInventory: context.documentInventory,
+      rule: context.rule
+    }));
+  }
+
+  if (given.allOf && Array.isArray(given.allOf)) {
+    // eslint-disable-next-line no-restricted-syntax
+    for (const [index, value] of given.allOf.entries()) {
+      errors.push(...checkTypeAndFormat(value, options, {
+        path: [...path, "allOf", index],
+        document: context.document,
+        documentInventory: context.documentInventory,
+        rule: context.rule
+      }));
+    }
+  }
+
+  return errors;
+};

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

@@ -0,0 +1,76 @@
+module.exports = function apqStandardResponseCodes(targetVal, options, context) {
+  const results = [];
+
+  if (!targetVal || !context?.path) return results;
+
+  const responses = targetVal.responses;
+  if (!responses || typeof responses !== 'object') return results;
+
+  const definedCodes = Object.keys(responses);
+  const pathIndex = context.path.indexOf('paths');
+  if (pathIndex === -1) return results;
+
+  const resourcePath = context.path[pathIndex + 1];
+  const verb = context.path[pathIndex + 2];
+
+  if (typeof resourcePath !== 'string' || typeof verb !== 'string') return results;
+
+  const exclusions = options?.['resources-exclusions'] || [];
+  if (exclusions.some(ex => {
+      const [exVerb, exPath] = ex.split(':');
+      return exVerb.toLowerCase() === verb.toLowerCase() && new RegExp(`^${exPath}$`).test(resourcePath);
+    })) return results;
+
+  const rulesConfig = options?.['required-codes-by-resources-paths'];
+  if (!rulesConfig) return results;
+
+  const rules = rulesConfig
+    .split(/[\n;]/) 
+    .map(r => r.trim())
+    .filter(Boolean)
+    .map(rule => {
+      const parts = rule.split(':');
+      if (parts.length < 3) return null;
+
+      const verbPart = parts[0].toLowerCase();
+      const codesPart = parts[parts.length - 1];
+      const regexPart = parts.slice(1, -1).join(':');
+
+      return {
+        verb: verbPart,
+        pathRegex: new RegExp(regexPart),
+        requiredCodes: codesPart.split(',').map(c => c.trim()).filter(Boolean)
+      };
+    }).filter(Boolean);
+
+  const matchedRule = rules.find(
+    r => r.verb === verb.toLowerCase() && r.pathRegex.test(resourcePath)
+  );
+
+  if (!matchedRule) return results;
+
+matchedRule.requiredCodes.forEach(ruleCode => {
+    let missing = false;
+    let msg = "";
+
+    if (ruleCode.includes('|')) {
+      const alternatives = ruleCode.split('|');
+      if (!alternatives.some(c => definedCodes.includes(c))) {
+        missing = true;
+        msg = `OAR039: Response code ${alternatives.join(' or ')} must be defined.`;
+      }
+    } else if (!definedCodes.includes(ruleCode)) {
+      missing = true;
+      msg = `OAR039: Response code ${ruleCode} must be defined.`;
+    }
+
+    if (missing) {
+      results.push({
+        message: msg,
+        path: context.path
+      });
+    }
+  });
+
+  return results;
+};

package/functions/apq-truthy-insensitive.js

@@ -0,0 +1,18 @@
+
+/**
+ * @param {Object} given
+ * @param {object} options
+ * @param {string} options.property
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const errors = [];
+
+  if (!given || Object.keys(given).some(key => key.toUpperCase() !== options.property.toUpperCase())) {
+    errors.push({
+      message: context.rule.message
+    });
+  }
+
+  return errors;
+};