feat: BN013 plugin to warn on unreferenced resources

README.md

@@ -248,6 +248,7 @@ This is the current list:
 |   |:white_check_mark:| BN009 | Statistics Collector - duplicate policies |  Warn on duplicate policies when no conditions are present or conditions are duplicates. |
 |   |:white_check_mark:| BN010 | Missing policies | Issue an error if a referenced policy is not present in the bundle. |
 |   |:white_check_mark:| BN011 | Check each XML file for well-formedness.|
+|   |:white_check_mark:| BN013 | Unreferenced resources. | Warn for resources that not referenced in any policy. Unreferenced resources are dead code. |
 |   |:white_check_mark:| BN012 | unreferrenced Target Endpoints | Check that each TargetEndpoint can be reached. |
 | Proxy Definition |   |   |   |   |
 |   |:white_check_mark:| PD001 | RouteRules to Targets | RouteRules should map to defined Targets. |

lib/package/plugins/BN013-unreferenced-resources.js

@@ -0,0 +1,204 @@
+/*
+  Copyright 2019-2024 Google LLC
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      https://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+const ruleId = require("../myUtil.js").getRuleId(),
+  util = require("util"),
+  xpath = require("xpath"),
+  debug = require("debug")("apigeelint:" + ruleId);
+
+const plugin = {
+  ruleId,
+  name: "Check for unreferenced resources",
+  message:
+    "Unreferenced resources are dead code; should be removed from bundles.",
+  fatal: false,
+  severity: 1, //1=warn, 2=error
+  nodeType: "Bundle",
+  enabled: true
+};
+
+const validResourceTypesForBoth = [
+  "jsc",
+  "java",
+  "py",
+  "xsl",
+  "wsdl",
+  "xsd",
+  "oas"
+];
+
+const profileMappings = {
+  apigeex: ["properties", "graphql"],
+  apigee: ["node", "hosted", "template"]
+};
+
+const onBundle = function (bundle, cb) {
+  const validResourceTypes = [];
+  validResourceTypes.push.apply(validResourceTypes, validResourceTypesForBoth);
+  validResourceTypes.push.apply(
+    validResourceTypes,
+    profileMappings[bundle.profile || "apigee"]
+  );
+
+  debug(`validResourceTypes: ${util.format(validResourceTypes)}`);
+
+  const resources = bundle.getResources(),
+    policies = bundle.getPolicies();
+
+  debug(`resources: ${util.format(resources)}`);
+  let flagged = false;
+  if (resources.length) {
+    resources.forEach((resource, rix) => {
+      debug(`resource(${rix}): ${resource.path} ${resource.fname}`);
+      const marker = "apiproxy/resources/",
+        ix = resource.path.lastIndexOf(marker);
+      if (ix < 0) {
+        return;
+      }
+      const trailingPath = resource.path.substr(ix + marker.length),
+        [rtype, rshortname] = trailingPath.split("/", 2);
+      debug(
+        `trailingPath(${trailingPath})  rtype(${rtype}) rshortname(${rshortname})`
+      );
+      if (!rshortname) {
+        debug(`no resource shortname.`);
+        return;
+      }
+      if (!validResourceTypes.includes(rtype)) {
+        debug(`${rtype} is not a valid resource type, punt.`);
+        return;
+      }
+
+      let found = false;
+      if (rtype == "java") {
+        /*
+         * Handle Java resources specially.
+         *
+         * We cannot tell by static analysis at this level if a specific Java
+         * jar will be used by any particular JavaCallout policy.  But we can
+         * tell if there is no JavaCallout policy, in which case we can be
+         * sure that every jar is unreferenced.
+         **/
+        found = policies.find((policy) => policy.getType() == "JavaCallout");
+      } else if (rtype == "properties") {
+        /*
+         * Punt on properties resources.
+         *
+         * The runtime sets variables with the contents of the
+         * properties file. We cannot tell if these variables are used
+         * by Java callouts, JS, or even sharedflows.
+         **/
+        found = true;
+      } else {
+        found = policies.find((policy, _pix) => {
+          const ptype = policy.getType();
+          /*
+           * Any text resource can be included in an AssignMessage/AssignVariable
+           * or RaiseFault/FaultResponse/AssignVariable .
+           **/
+          if (ptype == "AssignMessage" || ptype == "RaiseFault") {
+            const avpath =
+              ptype == "AssignMessage"
+                ? "AssignMessage"
+                : "RaiseFault/FaultResponse";
+            const rsrcUrls = xpath.select(
+              `/${avpath}/AssignVariable/ResourceURL/text()`,
+              policy.getElement()
+            );
+            debug(`rsrcUrl: ${util.format(rsrcUrls)}`);
+
+            // check any/all
+            return rsrcUrls.find(
+              (rsrcUrl) => rsrcUrl.data == `${rtype}://${rshortname}`
+            );
+          }
+
+          // now do checks for specific resource types
+          const rtypeMappings = {
+            xsl: { xpath: "ResourceURL/text()", ptype: "XSL" },
+            oas: {
+              xpath: "OASResource/text()",
+              ptype: "OASValidation"
+            },
+            py: { xpath: `ResourceURL/text()`, ptype: "Script" },
+            xsd: {
+              xpath: "ResourceURL/text()",
+              ptype: "MessageValidation"
+            },
+            wsdl: {
+              xpath: "ResourceURL/text()",
+              ptype: "MessageValidation"
+            },
+            graphql: {
+              xpath: "ResourceURL/text()",
+              ptype: "GraphQL"
+            }
+          };
+          const findit = (path1) => {
+            const rsrcUrls = xpath.select(path1, policy.getElement());
+            // check the first one. there should be only one.
+            return (
+              rsrcUrls &&
+              rsrcUrls.length &&
+              rsrcUrls[0].data == `${rtype}://${rshortname}`
+            );
+          };
+          if (rtypeMappings[rtype]) {
+            return (
+              ptype == rtypeMappings[rtype].ptype &&
+              findit(`/${ptype}/${rtypeMappings[rtype].xpath}`)
+            );
+          }
+
+          // handle jsc specially, because of IncludeURL
+          if (rtype == "jsc" && ptype == "Javascript") {
+            const rsrcUrls = xpath.select(
+              `/Javascript/IncludeURL/text()`,
+              policy.getElement()
+            );
+            // check any/all
+            if (
+              rsrcUrls.find((rsrcUrl) => rsrcUrl.data == `jsc://${rshortname}`)
+            ) {
+              return true;
+            }
+            return findit(`/Javascript/ResourceURL/text()`);
+          }
+
+          return false; // not found
+        });
+      }
+
+      if (!found) {
+        flagged = true;
+        debug(`unreferenced: ${resource.fname}`);
+        bundle.addMessage({
+          plugin,
+          entity: resource,
+          message: `Unreferenced resource ${rtype}/${resource.fname}. There are no policies that reference this resource.`
+        });
+      }
+    });
+  }
+  if (typeof cb == "function") {
+    cb(null, flagged);
+  }
+};
+
+module.exports = {
+  plugin,
+  onBundle
+};

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/AM-Assign-Variable-ResourceURL.xml

@@ -0,0 +1,15 @@
+<AssignMessage name='AM-Assign-Variable-ResourceURL'>
+  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
+  <AssignVariable>
+    <Name>xslContents</Name>
+    <ResourceURL>xsl://sheet3.xsl</ResourceURL>
+  </AssignVariable>
+  <AssignVariable>
+    <Name>jsContents</Name>
+    <ResourceURL>jsc://sourceFile1.js</ResourceURL>
+  </AssignVariable>
+  <AssignVariable>
+    <Name>wsdlContents</Name>
+    <ResourceURL>wsdl://example2.wsdl</ResourceURL>
+  </AssignVariable>
+</AssignMessage>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/AM-Inject-Proxy-Revision-Header.xml

@@ -0,0 +1,7 @@
+<AssignMessage name='AM-Inject-Proxy-Revision-Header'>
+  <Set>
+    <Headers>
+      <Header name='APIProxy'>{apiproxy.name} r{apiproxy.revision}</Header>
+    </Headers>
+  </Set>
+</AssignMessage>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/JS-testme.xml

@@ -0,0 +1,8 @@
+<Javascript name='JS-testme' timeLimit='1200' >
+  <Properties>
+    <!-- to retrieve properties in js code:   properties.prop1 -->
+    <Property name='prop1'>value-here</Property>
+  </Properties>
+  <IncludeURL>jsc://URI.js</IncludeURL>
+  <ResourceURL>jsc://sourceFile2.js</ResourceURL>
+</Javascript>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/MV-1.xml

@@ -0,0 +1,4 @@
+<MessageValidation name="MV-1">
+   <Source>message</Source> <!-- must be message type -->
+   <ResourceURL>xsd://example1.xsd</ResourceURL>
+</MessageValidation>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/MV-2.xml

@@ -0,0 +1,5 @@
+<MessageValidation name="MV-2">
+   <Source>message</Source> <!-- must be message type -->
+   <ResourceURL>wsdl://example1.wsdl</ResourceURL>
+   <SOAPMessage version='1.1'/> <!-- optional -->
+</MessageValidation>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/OAS-Basic.xml

@@ -0,0 +1,12 @@
+<OASValidation name="OAS-Basic">
+   <OASResource>oas://example1.yaml</OASResource>
+   <Options>
+      <ValidateMessageBody>true</ValidateMessageBody>
+      <AllowUnspecifiedParameters>
+         <Header>false</Header>
+         <Query>false</Query>
+         <Cookie>false</Cookie>
+      </AllowUnspecifiedParameters>
+   </Options>
+   <Source>request</Source>
+</OASValidation>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/PS-Set-Header.xml

@@ -0,0 +1,3 @@
+<Script name="PS-Set-Header">
+   <ResourceURL>py://setHeader1.py</ResourceURL>
+</Script>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/RF-Unknown-Request.xml

@@ -0,0 +1,24 @@
+<RaiseFault name='RF-Unknown-Request'>
+  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
+  <FaultResponse>
+    <AssignVariable>
+      <!--
+          Why anyone would want to set the contents of a python script into a
+          variable, I do not know. but it is possible.
+      -->
+      <Name>pyContents</Name>
+      <ResourceURL>py://setHeader2.py</ResourceURL>
+    </AssignVariable>
+    <Set>
+      <Payload contentType='application/json'>{
+  "error" : {
+    "code" : 404.01,
+    "message" : "that request was unknown; try a different request."
+  }
+}
+</Payload>
+      <StatusCode>404</StatusCode>
+      <ReasonPhrase>Not Found</ReasonPhrase>
+    </Set>
+  </FaultResponse>
+</RaiseFault>

test/fixtures/resources/BN013-unreferenced-resources/apiproxy/policies/XSL-Basic.xml

@@ -0,0 +1,15 @@
+<XSL name='XSL-Basic'>
+  <Source>outboundMessageTemplate</Source>
+  <OutputVariable>transformedContent</OutputVariable>
+  <ResourceURL>xsl://sheet1.xsl</ResourceURL>
+  <!--
+      Parameters are optional. reference them in the XSL as:
+      <xsl:param name="pwd" select="'default-value-1'"/>
+      <xsl:param name="converted" select="'default-value-2'"/>
+  -->
+  <Parameters ignoreUnresolvedVariables='true'>
+    <!-- use ref or value. if you include both, you get an error at deploy time
+         in Apigee X. -->
+    <Parameter name='additional' ref='variable-containing-value' value='hardcoded-value'/>
+  </Parameters>
+</XSL>