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

package/apq-spectral.yaml

@@ -30,6 +30,10 @@ functions:
   - apq-status-endpoint-check
   - apq-validate-structure
   - apq-numeric-parameter-integrity
+  - apq-path-pattern
+  - apq-query-params-optional
+  - apq-wso2-scopes-valid
+  - apq-numeric-path-param
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -46,14 +50,12 @@ rules:
         match: "^https://"
   apiq:OAR002:
     description: "A wrong scope definition may cause problems to import the API definition into WSO2."
-    message: "OAR002: Scope definition must include the 'key' attribute along with 'name' and 'roles'."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR002.md"
     severity: "error"
-    given: "$.x-wso2-security.apim.x-wso2-scopes[*]"
+    given: "$.x-wso2-security.apim.x-wso2-scopes"
     then:
-      - function: "truthy"
-        field: "key"
-        message: "Scope must define a 'key' attribute."
+      function: apq-wso2-scopes-valid
   apiq:OAR003:
     description: "A description can help other developers to understand the correct use of the scope."
     message: "OAR003: Scope must define a 'description' attribute."
@@ -194,7 +196,7 @@ rules:
     message: "OAR016: Numeric types must use a valid format for their type."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR016.md"
     severity: error
-    given: "$..[?(@ && (@.type=='number' || @.type=='integer'))]"
+    given: "$..[?(@ && (@.type=='number' || @.type=='integer' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
     then:
       function: schema
       functionOptions:
@@ -485,7 +487,7 @@ rules:
     message: "OAR037: String schemas must specify a valid format (date, date-time, password, byte, binary, email, uuid, uri, hostname, ipv4, ipv6, HEX, HEX(16), json, xml, or base64), or a valid pattern when no format is defined."
     severity: error
     resolved: false
-    given: "$..[?(@ && @.type=='string')]"
+    given: "$..[?(@ && @.type)]"
     then:
       function: apq-schema-format
   apiq:OAR038:
@@ -686,7 +688,7 @@ rules:
     message: "OAR052: Numeric types requires a format"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR052.md"
     severity: warn
-    given: "$..[?(@ && (@.type == 'integer' || @.type == 'number'))]"
+    given: "$..[?(@ && (@.type == 'integer' || @.type == 'number' || (@.type && @.type.indexOf && (@.type.indexOf('integer') > -1 || @.type.indexOf('number') > -1))))]"
     then:
       field: format
       function: truthy
@@ -716,12 +718,18 @@ rules:
         match: ^(http(s)?:\/\/.)[-a-zA-Z0-9@:%._\+~#=]{2,256}\.apiquality.io\b([-a-zA-Z0-9@:%_\+.~#?&\/=]*)$
   apiq:OAR060:
     description: "All query parameters must be defined as optional."
-    message: "OAR060: All query parameter must be optional (required: false)."
+    message: "{{error}}"
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'query')]"
+    given:
+      - "$.paths[*][get,put,post,delete,options,head,patch,trace].parameters[?(@.in == 'query')]"
+      - "$.paths[*].parameters[?(@.in == 'query')]"
+      - "$.components.parameters[?(@.in == 'query')]"
+      - "$.parameters[?(@.in == 'query')]"
     then:
       field: "required"
-      function: falsy
+      function: apq-query-params-optional
+      functionOptions:
+        path-exclusions: "/status"
   apiq:OAR061:
     description: "Ensure get have mandatory response codes"
     message: "OAR061: Ensure get have the mandatory response codes"
@@ -836,10 +844,7 @@ rules:
     severity: error
     given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'path')]"
     then:
-      field: "schema.type"
-      function: pattern
-      functionOptions:
-        match: "^(?!integer|number)"
+      function: apq-numeric-path-param
   apiq:OAR071:
     description: "Query parameters 'param1', 'param2', and 'param3' must be defined in the operation."
     message: "OAR071: Query parameters 'param1', 'param2', and 'param3' must be defined."
@@ -876,15 +881,15 @@ rules:
     severity: error
     resolved: false
     given:
-      - "$..[?(@ && @.in && @.schema && (@.schema.type == 'integer' || @.schema.type == 'number'))].schema"
-      - "$..[?(@ && @.in && (@.type == 'integer' || @.type == 'number'))]"
+      - "$..[?(@ && @.in && @.schema && (@.schema.type == 'integer' || @.schema.type == 'number' || (@.schema.type && @.schema.type.indexOf && (@.schema.type.indexOf('integer') > -1 || @.schema.type.indexOf('number') > -1))))].schema"
+      - "$..[?(@ && @.in && (@.type == 'integer' || @.type == 'number' || (@.type && @.type.indexOf && (@.type.indexOf('integer') > -1 || @.type.indexOf('number') > -1))))]"
     then:
       function: apq-numeric-parameter-integrity
   apiq:OAR075:
     description: "String parameters should have minLength, maxLength, pattern (regular expression), or enum restriction."
     message: "OAR075: String parameters should have minLength, maxLength, pattern, or enum restriction."
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@ && @.schema && @.schema.type == 'string' && @.in == 'path')]"
+    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@ && @.schema && (@.schema.type == 'string' || (@.schema.type && @.schema.type.indexOf && @.schema.type.indexOf('string') > -1)) && @.in == 'path')]"
     then:
       function: schema
       functionOptions:
@@ -902,7 +907,7 @@ rules:
     message: "OAR076: Schema should use well-defined type and format."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR076.md"
     severity: error
-    given: "$..[?(@ && (@.type=='number' || @.type=='integer'))]"
+    given: "$..[?(@ && (@.type=='number' || @.type=='integer' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
     then:
       function: schema
       functionOptions:
@@ -1000,7 +1005,7 @@ rules:
       functionOptions:
         notMatch: "^password$"
   apiq:OAR085:
-    description: "The OpenAPI version must be one of: 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0, 3.2.0."
+    description: "The OpenAPI version must be one of: 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0."
     message: "{{error}}"
     severity: warn
     given:
@@ -1009,7 +1014,7 @@ rules:
     then:
       function: apq-valid-openapi-version
       functionOptions:
-        valid-versions: "2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.1.0,3.2.0"
+        valid-versions: "2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.0.4,3.1.0,3.1.1,3.1.2,3.2.0"
   apiq:OAR086:
     description: "Descriptions must begin with a capital letter, end with a period, and not be empty."
     message: "OAR086: Descriptions must begin with a capital letter, end with a period, and not be empty."
@@ -1264,4 +1269,14 @@ rules:
       - "$.components.schemas[*]"
       - "$.definitions[*]"
     then:
-      function: apq-required-fields-exist
+      function: apq-required-fields-exist
+  apiq:OAR116:
+    description: "Every API path must match the configured regular expression."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR116.md"
+    severity: error
+    given: "$.paths.*~"
+    then:
+      function: apq-path-pattern
+      functionOptions:
+        pattern: "^/"

package/functions/apq-binary-format-check.js

@@ -5,7 +5,6 @@ module.exports = (schema, options = {}, context) => {
     return results;
   }
 
-  // Fields that must have byte or binary format
   const fieldsToCheck = (options['fields-to-apply'] || 'product,line,price')
     .split(',')
     .map(f => f.trim().toLowerCase());
@@ -13,7 +12,6 @@ module.exports = (schema, options = {}, context) => {
   const properties = schema.properties || {};
 
   Object.entries(properties).forEach(([propName, propSchema]) => {
-    // Only check if this property is in our list
     if (!fieldsToCheck.includes(propName.toLowerCase())) {
       return;
     }
@@ -22,13 +20,17 @@ module.exports = (schema, options = {}, context) => {
       return;
     }
 
-    // Check if it's a string type
-    if (propSchema.type !== 'string') {
+    const type = propSchema.type;
+    const isStringType = type === 'string' || (Array.isArray(type) && type.includes('string'));
+    if (!isStringType) {
       return;
     }
 
     const format = propSchema.format || '';
-    if (format !== 'byte' && format !== 'binary') {
+    const hasBinaryFormat = format === 'byte' || format === 'binary';
+    const hasContentEncoding = propSchema.contentEncoding !== undefined
+      || propSchema.contentMediaType !== undefined;
+    if (!hasBinaryFormat && !hasContentEncoding) {
       results.push({
         message: `OAR082: Property '${propName}' must define a 'byte' or 'binary' format (currently: ${format || 'missing'}).`,
         path: [...context.path, 'properties', propName, 'type'],

package/functions/apq-numeric-parameter-integrity.js

@@ -9,7 +9,9 @@ module.exports = (node, options, context) => {
   if (!node || typeof node !== 'object') return results;
 
   const { type } = node;
-  if (type !== 'integer' && type !== 'number') return results;
+  const types = Array.isArray(type) ? type : [type];
+  const isNumeric = types.indexOf('integer') > -1 || types.indexOf('number') > -1;
+  if (!isNumeric) return results;
 
   const has = (field) => Object.prototype.hasOwnProperty.call(node, field);
   const hasMin = has('minimum');

package/functions/apq-numeric-path-param.js

@@ -0,0 +1,34 @@
+/**
+ * @param {object} param   the parameter object (given selects params with `in: path`)
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (param, options, context) => {
+  const results = [];
+  if (!param || typeof param !== 'object' || param.in !== 'path') return results;
+
+  let typeVal;
+  let typePath;
+  if (param.schema && param.schema.type !== undefined) {
+    typeVal = param.schema.type;
+    typePath = [...context.path, 'schema', 'type'];
+  } else if (param.type !== undefined) {
+    typeVal = param.type;
+    typePath = [...context.path, 'type'];
+  } else {
+    return results;
+  }
+
+  const types = Array.isArray(typeVal) ? typeVal : [typeVal];
+  const isNumeric = types.indexOf('integer') > -1
+    || types.indexOf('number') > -1
+    || types.indexOf('float') > -1;
+  if (!isNumeric) return results;
+
+  const ruleCode = context.rule.name.split(':').pop();
+  results.push({
+    message: `${ruleCode}: Parameters in path should not be numeric.`,
+    path: typePath,
+  });
+  return results;
+};

package/functions/apq-path-pattern.js

@@ -0,0 +1,14 @@
+module.exports = (targetVal, options = {}) => {
+  const patternStr = (options && options.pattern) || '^/';
+
+  if (typeof targetVal !== 'string') {
+    return [];
+  }
+
+  const regex = new RegExp(patternStr);
+  if (!regex.test(targetVal)) {
+    return [{ message: `OAR116: Path does not match the required pattern: ${patternStr}` }];
+  }
+
+  return [];
+};

package/functions/apq-query-params-optional.js

@@ -0,0 +1,182 @@
+const HTTP_VERBS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+
+// Guards against a cycle in a `$ref` chain (A -> B -> A).
+const MAX_REF_DEPTH = 10;
+
+// The `$ref` usage map depends only on the source document, so cache it per document instead of
+// rebuilding it on every matched parameter.
+const usageCache = new WeakMap();
+
+const issue = () => [{ message: 'OAR060: All query parameter must be optional (required: false).' }];
+
+function parseExclusions(value) {
+  return new Set(
+    String(value === undefined || value === null ? '' : value)
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Split a local JSON pointer (`#/components/parameters/Foo`) into its decoded segments.
+ * Returns null for external refs and for anything that is not a document-local pointer.
+ */
+function refToSegments(ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) {
+    return null;
+  }
+  return ref.slice(2).split('/').map((raw) => {
+    let segment = raw;
+    try {
+      segment = decodeURIComponent(raw);
+    } catch (e) {
+      segment = raw;
+    }
+    return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+  });
+}
+
+function getAt(doc, segments) {
+  return segments.reduce(
+    (node, segment) => (node !== null && typeof node === 'object' ? node[segment] : undefined),
+    doc,
+  );
+}
+
+const keyOf = (segments) => JSON.stringify(segments);
+
+/**
+ * The two containers the rule's `given` scans for shared parameter definitions:
+ * `components.parameters.<name>` (OpenAPI 3) and `parameters.<name>` (OpenAPI 2).
+ */
+function definitionSegments(path) {
+  if (path[0] === 'components' && path[1] === 'parameters' && path.length >= 3) {
+    return path.slice(0, 3);
+  }
+  if (path[0] === 'parameters' && path.length >= 2) {
+    return path.slice(0, 2);
+  }
+  return null;
+}
+
+const isSharedDefinitionRef = (segments) => segments !== null
+  && ((segments.length === 3 && segments[0] === 'components' && segments[1] === 'parameters')
+    || (segments.length === 2 && segments[0] === 'parameters'));
+
+/** Map of shared-definition pointer -> set of API paths that reference it through a `$ref`. */
+function buildRefUsages(doc) {
+  const usages = new Map();
+  const paths = doc && typeof doc === 'object' ? doc.paths : undefined;
+  if (!paths || typeof paths !== 'object') {
+    return usages;
+  }
+
+  Object.keys(paths).forEach((apiPath) => {
+    const pathItem = paths[apiPath];
+    if (!pathItem || typeof pathItem !== 'object') {
+      return;
+    }
+
+    const parameterLists = [pathItem.parameters];
+    HTTP_VERBS.forEach((verb) => {
+      const operation = pathItem[verb];
+      if (operation && typeof operation === 'object') {
+        parameterLists.push(operation.parameters);
+      }
+    });
+
+    parameterLists.forEach((list) => {
+      if (!Array.isArray(list)) {
+        return;
+      }
+      list.forEach((parameter) => {
+        let current = parameter;
+        for (let depth = 0; depth < MAX_REF_DEPTH; depth += 1) {
+          if (!current || typeof current !== 'object' || typeof current.$ref !== 'string') {
+            break;
+          }
+          const segments = refToSegments(current.$ref);
+          if (segments === null) {
+            break;
+          }
+          const key = keyOf(segments);
+          if (!usages.has(key)) {
+            usages.set(key, new Set());
+          }
+          usages.get(key).add(apiPath);
+          const next = getAt(doc, segments);
+          if (!next || next === current) {
+            break;
+          }
+          current = next;
+        }
+      });
+    });
+  });
+
+  return usages;
+}
+
+function refUsagesFor(doc) {
+  if (!doc || typeof doc !== 'object') {
+    return new Map();
+  }
+  let cached = usageCache.get(doc);
+  if (cached === undefined) {
+    cached = buildRefUsages(doc);
+    usageCache.set(doc, cached);
+  }
+  return cached;
+}
+
+/**
+ * True when the match landed on a `$ref` to a shared definition the rule also scans on its own —
+ * either a use site under `paths`, or one shared definition aliasing another.
+ *
+ * Spectral runs the rule over the resolved document, so it matches such a parameter once here and
+ * once at the definition it points to. Reporting is left to the definition-site match, which is
+ * also the only place Sonar reports it (its AST visits the definition, never the use sites).
+ */
+function isRefToSharedDefinition(source, path) {
+  const parameterPath = path[path.length - 1] === 'required' ? path.slice(0, -1) : path;
+  const node = getAt(source, parameterPath);
+  if (!node || typeof node !== 'object' || typeof node.$ref !== 'string') {
+    return false;
+  }
+  return isSharedDefinitionRef(refToSegments(node.$ref));
+}
+
+module.exports = (targetVal, options = {}, context = {}) => {
+  const exclusions = parseExclusions((options || {})['path-exclusions']);
+  const path = (context && context.path) || [];
+  const source = context && context.document ? context.document.data : undefined;
+
+  if (isRefToSharedDefinition(source, path)) {
+    return [];
+  }
+
+  if (path[0] === 'paths') {
+    const apiPath = path.find((p) => typeof p === 'string' && p.startsWith('/'));
+    if (apiPath && exclusions.has(apiPath)) {
+      return [];
+    }
+  } else if (exclusions.size > 0) {
+    // A shared definition has no path of its own: the AST/JSONPath match lands on
+    // `components.parameters.<name>` (or `parameters.<name>` in OpenAPI 2). Exclude it only when
+    // every path that references it is excluded — an unreferenced definition stays in scope.
+    const definition = definitionSegments(path);
+    const usages = definition === null
+      ? undefined
+      : refUsagesFor(source).get(keyOf(definition));
+    if (usages !== undefined && usages.size > 0 && [...usages].every((u) => exclusions.has(u))) {
+      return [];
+    }
+  }
+
+  if (targetVal === true || targetVal === 'true') {
+    return issue();
+  }
+
+  return [];
+};

package/functions/apq-required-fields-exist.js

@@ -6,7 +6,10 @@
 module.exports = (given, options, context) => {
   const results = [];
 
-  if (!given || given.type !== 'object') return results;
+  if (!given) return results;
+  const t = given.type;
+  const isObjectType = t === 'object' || (Array.isArray(t) && t.indexOf('object') > -1);
+  if (!isObjectType) return results;
 
   const { required, properties } = given;
   if (!Array.isArray(required)) return results;

package/functions/apq-schema-format.js

@@ -16,6 +16,12 @@ function isValidPattern(pattern) {
 module.exports = (targetVal, _options, context) => {
   const typePath = [...context.path, 'type'];
 
+  const type = targetVal.type;
+  const isStringType = type === 'string' || (Array.isArray(type) && type.includes('string'));
+  if (!isStringType) {
+    return [];
+  }
+
   const format = targetVal.format;
   if (format !== undefined && format !== null) {
     if (!VALID_FORMATS.has(String(format).toLowerCase())) {

package/functions/apq-valid-openapi-version.js

@@ -1,4 +1,4 @@
-const DEFAULT_VALID_VERSIONS = '2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.1.0,3.2.0';
+const DEFAULT_VALID_VERSIONS = '2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.0.4,3.1.0,3.1.1,3.1.2,3.2.0';
 
 /**
  * @param {string} targetVal

package/functions/apq-wso2-scopes-valid.js

@@ -0,0 +1,58 @@
+/**
+ * @param {*} targetVal the `x-wso2-scopes` container node value
+ * @param {object} _options unused
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+const DEFINITION_WRONG = "OAR002: WSO2 scopes definition is wrong";
+const REQUIRED_PROP = "OAR002: WSO2 scope '{0}' is required";
+const REQUIRED_PROPERTIES = ['name', 'key', 'roles'];
+
+const requiredMessage = (prop) => REQUIRED_PROP.replace('{0}', prop);
+
+// A scope property counts as "required but missing" when it is absent, null, a
+// blank string, or an empty collection ([] / {}) — mirrors Sonar's OAR002 check.
+const isEmptyValue = (value) =>
+  value === null
+  || (typeof value === 'string' && value.trim() === '')
+  || (Array.isArray(value) && value.length === 0)
+  || (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0);
+
+module.exports = (targetVal, _options, context) => {
+  const errors = [];
+  const basePath = context.path || [];
+
+  if (targetVal === null || typeof targetVal !== 'object') {
+    errors.push({ message: DEFINITION_WRONG, path: basePath });
+    return errors;
+  }
+
+  const entries = Array.isArray(targetVal)
+    ? targetVal.map((scope, index) => [index, scope])
+    : Object.keys(targetVal).map((key) => [key, targetVal[key]]);
+
+  if (entries.length === 0) {
+    errors.push({ message: DEFINITION_WRONG, path: basePath });
+    return errors;
+  }
+
+  entries.forEach(([key, scope]) => {
+    const scopePath = [...basePath, key];
+
+    if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) {
+      REQUIRED_PROPERTIES.forEach((prop) => {
+        errors.push({ message: requiredMessage(prop), path: scopePath });
+      });
+      return;
+    }
+
+    REQUIRED_PROPERTIES.forEach((prop) => {
+      if (!Object.prototype.hasOwnProperty.call(scope, prop)) {
+        errors.push({ message: requiredMessage(prop), path: scopePath });
+      } else if (isEmptyValue(scope[prop])) {
+        errors.push({ message: requiredMessage(prop), path: [...scopePath, prop] });
+      }
+    });
+  });
+
+  return errors;
+};

package/package.json

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