CLOUDP-283086: Restructure and identify resource

Author: lovisaberggren

tools/ipa/Makefile

@@ -21,12 +21,12 @@ setup: deps devtools ## Set up dev env
 .PHONY: linterr
 linterr: ## Run spectral linter on foas
 	@echo "==> Running spectral linter"
-	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=ruleset.yaml
+	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=ipa-spectral.yaml -v
 
 .PHONY: lintwarn
 lintwarn: ## Run spectral linter on foas
 	@echo "==> Running spectral linter"
-	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=ruleset.yaml --fail-severity=warn
+	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=ipa-spectral --fail-severity=warn -v
 
 .PHONY: help
 .DEFAULT_GOAL := help

tools/ipa/functions/hasDescription.js

@@ -0,0 +1,2 @@
+extends:
+  - ./rulesets/IPA-104.yaml

tools/ipa/ipa-spectral.yaml

@@ -0,0 +1,15 @@
+# IPA-104: Get
+# http://go/ipa/104
+
+functions:
+  - eachResourceHasGetMethod
+
+rules:
+  xgen-IPA-104-resource-has-GET:
+    description: "APIs must provide a get method for resources. http://go/ipa/104"
+    message: "{{error}} http://go/ipa/117"
+    severity: error
+    given: "$.paths"
+    then:
+      field: "@key"
+      function: "eachResourceHasGetMethod"

tools/ipa/ruleset.yaml

@@ -0,0 +1,95 @@
+const ERROR_MESSAGE = "APIs must provide a get method for resources."
+
+export default (input, _, context) => {
+  if (isChild(input) || isCustomMethod(input)) {
+    return
+  }
+
+  const oas = context.documentInventory.resolved
+
+  const resourcePaths = getResourcePaths(input, Object.keys(oas.paths))
+
+  if (isSingletonResource(resourcePaths)) {
+    // Singleton resource, may have custom methods
+    if (!hasGetMethod(oas.paths[resourcePaths[0]])) {
+      return [
+        {
+          message: ERROR_MESSAGE
+        }
+      ]
+    }
+  } else if (isNormalResource(resourcePaths)) {
+    // Normal resource, may have custom methods
+    if (!hasGetMethod(oas.paths[resourcePaths[1]])) {
+      return [
+        {
+          message: ERROR_MESSAGE
+        }
+      ]
+    }
+  }
+}
+
+function isChild(path) {
+  return path.endsWith("}")
+}
+
+function isCustomMethod(path) {
+  return path.includes(":")
+}
+
+/**
+ * Get all paths for a resource based on the parent path
+ *
+ * @param parent the parent path string
+ * @param allPaths all paths as an array of strings
+ * @returns {*} a string array of all paths for a resource, including the parent
+ */
+function getResourcePaths(parent, allPaths) {
+  const childPathPattern = new RegExp(`^${parent}/{[a-zA-Z]+}$`);
+  const customMethodPattern = new RegExp(`^${parent}/{[a-zA-Z]+}:+[a-zA-Z]+$`);
+  return allPaths.filter(p => parent === p || childPathPattern.test(p) || customMethodPattern.test(p));
+}
+
+/**
+ * Checks if a resource is a singleton resource based on the paths for the
+ * resource. The resource may have custom methods.
+ *
+ * @param resourcePaths all paths for the resource as an array of strings
+ * @returns {boolean}
+ */
+function isSingletonResource(resourcePaths) {
+  if (resourcePaths.length === 1) {
+    return true
+  }
+  const additionalPaths = resourcePaths.slice(1)
+  return !additionalPaths.some((p) => !isCustomMethod(p))
+}
+
+/**
+ * Checks if a resource is a normal resource based on the paths for the
+ * resource. The resource may have custom methods.
+ *
+ * @param resourcePaths all paths for the resource as an array of strings
+ * @returns {boolean}
+ */
+function isNormalResource(resourcePaths) {
+  if (resourcePaths.length === 2 && isChild(resourcePaths[1])) {
+    return true
+  }
+  if (resourcePaths.length < 3 || !isChild(resourcePaths[1])) {
+    return false
+  }
+  const additionalPaths = resourcePaths.slice(2)
+  return !additionalPaths.some((p) => !isCustomMethod(p))
+}
+
+/**
+ * Checks if a path object has a GET method
+ *
+ * @param pathObject the path object to evaluate
+ * @returns {boolean}
+ */
+function hasGetMethod(pathObject) {
+  return Object.keys(pathObject).some((o) => o === "get")
+}