Empty commit to open PR

Update release docs to include release artifacts

CONTRIBUTING.md

@@ -24,6 +24,47 @@ Here are a few things you can do that will increase the likelihood of your pull
 - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
 - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
+## Cutting a new release
+
+<details>
+
+_Note: these instructions are for maintainers_
+
+1. Update the version number in [package.json](https://github.com/advanced-security/maven-dependency-submission-action/blob/main/package.json) and run `npm i` to update the lockfile. This is also a good time to make sure that the `dist/index.js` file is up to date by running `npm run build`.
+2. Go to [Draft a new
+   release](https://github.com/advanced-security/maven-dependency-submission-action/releases/new)
+   in the Releases page.
+3. Make sure that the `Publish this Action to the GitHub Marketplace`
+   checkbox is enabled
+
+<img width="481" alt="Screenshot 2022-06-15 at 12 08 19" src="https://user-images.githubusercontent.com/2161/173822484-4b60d8b4-c674-4bff-b5ff-b0c4a3650ab7.png">
+
+4. Click "Choose a tag" and then "Create new tag", where the tag name
+   will be your version prefixed by a `v` (e.g. `v4.1.2`).
+5. Use a version number for the release title (e.g. "4.1.2").
+
+<img width="700" alt="Screenshot 2022-06-15 at 12 08 36" src="https://user-images.githubusercontent.com/2161/173822548-33ab3432-d679-4dc1-adf8-b50fdaf47de3.png">
+
+6. Add your release notes. If this is a major version make sure to
+   include a small description of the biggest changes in the new version.
+7. Build the release executables by manually triggering [this action](https://github.com/advanced-security/maven-dependency-submission-action/actions/workflows/publish_executables.yml). The output of this action will be a zip file that you should download, extract, and drag into the binaries section. There should be three files there: ending in `-linux`, `-macos`, and `-win.exe`.
+8. Click "Publish Release".
+
+You now have a tag and release using the semver version you used
+above. The last remaining thing to do is to move the dynamic version
+identifier to match the current SHA. This allows users to adopt a
+major version number (e.g. `v1`) in their workflows while
+automatically getting all the
+minor/patch updates.
+
+To do this just checkout `main`, force-create a new annotated tag, and push it:
+
+```
+git tag -fa v4 -m "Updating v4 to 4.1.2"
+git push origin v4 --force
+```
+</details>
+
 ## Resources
 
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)

README.md

@@ -4,8 +4,6 @@ This is a GitHub Action that will generate a complete dependency graph for a Mav
 
 The action will invoke maven using the `com.github.ferstl:depgraph-maven-plugin:4.0.2` plugin to generate JSON output of the complete dependency graph, which is then processed and submitted using the [Dependency Submission Toolkit](https://github.com/github/dependency-submission-toolkit) to the GitHub repository.
 
-> **Warning** The dependency submission APIs and toolkit are still currently in beta and as such subject to changes in future releases.
-
 
 ## Usage
 
@@ -35,6 +33,7 @@ This action writes informations in the repository dependency graph, so if you ar
 
 * `snapshot-dependency-file-name`: An optional user control file path to the POM file, requires `snapshot-include-file-name` to be `true` for the value to be submitted.
 
+* `correlator`: An optional identifier to distinguish between multiple dependency snapshots of the same type. Defaults to the [job_id](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_id) of the current job.
 
 ## Examples
 
@@ -48,7 +47,37 @@ Generating and submitting a dependency snapshot using the defaults:
 Upon success it will generate a snapshot captured from Maven POM like;
 ![Screenshot 2022-08-15 at 09 33 47](https://user-images.githubusercontent.com/681306/184603264-3cd69fda-75ff-4a46-b014-630acab60fab.png)
 
+### Configuring for Matrix-Based Workflows
 
+To ensure that the job parameter of the submission remains unique when the action is being called from a workflow that has a matrix, you can pass a `correlator` to the action. This identifier will be appended to the default correlator propterty of a job, ensuring uniqueness across matrix-based workflows. When dealing with Maven-based Java projects that utilize different `pom.xml` files across matrix jobs, you can specify the `directory` relevant to each matrix job. This ensures that the dependency snapshot accurately reflects the dependencies for each specific configuration.
+
+Example of specifying `pom.xml` files for different matrix jobs:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - java-version: 8
+            directory: project1
+          - java-version: 11
+            directory: project2
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up JDK ${{ matrix.java-version }}
+      uses: actions/setup-java@v2
+      with:
+        java-version: ${{ matrix.java-version }}
+    - name: Submit Dependency Snapshot
+      uses: advanced-security/maven-dependency-submission-action@v3
+       with:
+        directory: ${{ matrix.directory }}
+        correlator: ${{ github.job }}-${{ matrix.directory }}
+```
+
+In this example, the action is configured to use different working directories based on the Java version specified in the matrix. This ensures that the dependency snapshot is accurate for each Java version being tested.
 
 ## Command Line Usage
 

action.yml

@@ -64,6 +64,12 @@ inputs:
     description: The URL to the detector that generated the dependency snapshot
     type: string
 
+  correlator:
+    description: An optional identifier to distinguish between multiple dependency snapshots of the same type
+    type: string
+    required: false
+    default: ''
+
 runs:
   using: node20
   main: dist/index.js

dist/index.js

@@ -47,13 +47,19 @@ class MavenDependencyGraph {
             const artifact = this.packageUrlToArtifact[depPackage.packageURL.toString()];
             let scope = getDependencyScopeForMavenScope(artifact.scopes);
             manifest.addDirectDependency(depPackage, scope);
-            function addTransitiveDeps(dependencies) {
+            function addTransitiveDeps(dependencies, seen = new Set()) {
                 if (dependencies) {
                     dependencies.forEach(transitiveDep => {
-                        const transitiveDepArtifact = packageUrlToArtifact[transitiveDep.packageURL.toString()];
+                        let purl = transitiveDep.packageURL.toString();
+                        if (seen.has(purl)) {
+                            // we're in a cycle! skip this one.
+                            return;
+                        }
+                        const transitiveDepArtifact = packageUrlToArtifact[purl];
                         const transitiveDepScope = getDependencyScopeForMavenScope(transitiveDepArtifact.scopes);
                         manifest.addIndirectDependency(transitiveDep, transitiveDepScope);
-                        addTransitiveDeps(transitiveDep.dependencies);
+                        seen.add(purl);
+                        addTransitiveDeps(transitiveDep.dependencies, seen);
                     });
                 }
             }
@@ -251,6 +257,10 @@ function run() {
                 sha: core.getInput('snapshot-sha'),
                 ref: core.getInput('snapshot-ref'),
             };
+            const correlator = core.getInput('correlator');
+            if (correlator) {
+                snapshotConfig.correlator = correlator;
+            }
             const detectorName = core.getInput('detector-name');
             if (detectorName !== '') {
                 snapshotConfig.detector = {
@@ -480,10 +490,10 @@ const depgraph_1 = __nccwpck_require__(8047);
 const maven_runner_1 = __nccwpck_require__(7433);
 const file_utils_1 = __nccwpck_require__(799);
 const packageData = __nccwpck_require__(2876);
-const DEPGRAPH_MAVEN_PLUGIN_VERSION = '4.0.2';
+const DEPGRAPH_MAVEN_PLUGIN_VERSION = '4.0.3';
 function generateSnapshot(directory, mvnConfig, snapshotConfig) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a;
+        var _a, _b;
         const depgraph = yield generateDependencyGraph(directory, mvnConfig);
         try {
             const mavenDependencies = new depgraph_1.MavenDependencyGraph(depgraph);
@@ -505,11 +515,14 @@ function generateSnapshot(directory, mvnConfig, snapshotConfig) {
             const detector = (_a = snapshotConfig === null || snapshotConfig === void 0 ? void 0 : snapshotConfig.detector) !== null && _a !== void 0 ? _a : getDetector();
             const snapshot = new dependency_submission_toolkit_1.Snapshot(detector, snapshotConfig === null || snapshotConfig === void 0 ? void 0 : snapshotConfig.context, snapshotConfig === null || snapshotConfig === void 0 ? void 0 : snapshotConfig.job);
             snapshot.addManifest(manifest);
-            const specifiedRef = getNonEmtptyValue(snapshotConfig === null || snapshotConfig === void 0 ? void 0 : snapshotConfig.ref);
+            snapshot.job.correlator = (snapshotConfig === null || snapshotConfig === void 0 ? void 0 : snapshotConfig.correlator)
+                ? snapshotConfig.correlator
+                : (_b = snapshot.job) === null || _b === void 0 ? void 0 : _b.correlator;
+            const specifiedRef = getNonEmptyValue(snapshotConfig === null || snapshotConfig === void 0 ? void 0 : snapshotConfig.ref);
             if (specifiedRef) {
                 snapshot.ref = specifiedRef;
             }
-            const specifiedSha = getNonEmtptyValue(snapshot === null || snapshot === void 0 ? void 0 : snapshot.sha);
+            const specifiedSha = getNonEmptyValue(snapshot === null || snapshot === void 0 ? void 0 : snapshot.sha);
             if (specifiedSha) {
                 snapshot.sha = specifiedSha;
             }
@@ -609,7 +622,7 @@ function getRepositoryRelativePath(file) {
     core.debug(`Snapshot relative file =  ${result}`);
     return result;
 }
-function getNonEmtptyValue(str) {
+function getNonEmptyValue(str) {
     if (str) {
         const trimmed = str.trim();
         if (trimmed.length > 0) {
@@ -33288,7 +33301,7 @@ exports.submitSnapshot = L;
 /***/ ((module) => {
 
 "use strict";
-module.exports = JSON.parse('{"name":"maven-dependency-submission-action","version":"4.1.0","description":"Submit Maven dependencies to GitHub dependency submission API","main":"index.js","scripts":{"base-build":"npm ci && tsc","build":"npm run base-build && npm exec -- @vercel/ncc build --source-map lib/src/index.js","build-exe":"npm run build && pkg package.json --compress Gzip","test":"vitest --run"},"repository":{"type":"git","url":"git+https://github.com/advanced-security/maven-dependency-submission-action.git"},"keywords":[],"author":"GitHub, Inc","license":"MIT","bugs":{"url":"https://github.com/advanced-security/maven-dependency-submission-action/issues"},"homepage":"https://github.com/advanced-security/maven-dependency-submission-action","dependencies":{"@actions/core":"^1.10.1","@actions/exec":"^1.1.1","@github/dependency-submission-toolkit":"^2.0.0","commander":"^12.0.0","packageurl-js":"^1.2.0"},"devDependencies":{"@types/chai":"^4.3.1","@vercel/ncc":"^0.38.1","chai":"^4.3.6","@yao-pkg/pkg":"^5.11.5","ts-node":"^10.9.2","typescript":"^5.3.3","vitest":"^1.2.1"},"bin":{"cli":"lib/src/executable/cli.js"},"pkg":{"targets":["node20-linux-x64","node20-win-x64","node20-macos-x64"],"assets":["package.json"],"publicPackages":"*","outputPath":"cli"}}');
+module.exports = JSON.parse('{"name":"maven-dependency-submission-action","version":"4.1.2","description":"Submit Maven dependencies to GitHub dependency submission API","main":"index.js","scripts":{"base-build":"npm ci && tsc","build":"npm run base-build && npm exec -- @vercel/ncc build --source-map lib/src/index.js","build-exe":"npm run build && pkg package.json --compress Gzip","test":"vitest --run"},"repository":{"type":"git","url":"git+https://github.com/advanced-security/maven-dependency-submission-action.git"},"keywords":[],"author":"GitHub, Inc","license":"MIT","bugs":{"url":"https://github.com/advanced-security/maven-dependency-submission-action/issues"},"homepage":"https://github.com/advanced-security/maven-dependency-submission-action","dependencies":{"@actions/core":"^1.10.1","@actions/exec":"^1.1.1","@github/dependency-submission-toolkit":"^2.0.0","commander":"^12.0.0","packageurl-js":"^1.2.0"},"devDependencies":{"@types/chai":"^4.3.1","@vercel/ncc":"^0.38.1","chai":"^4.3.6","@yao-pkg/pkg":"^5.11.5","ts-node":"^10.9.2","typescript":"^5.3.3","vitest":"^1.6.1"},"bin":{"cli":"lib/src/executable/cli.js"},"pkg":{"targets":["node20-linux-x64","node20-win-x64","node20-macos-x64"],"assets":["package.json"],"publicPackages":"*","outputPath":"cli"}}');
 
 /***/ })
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "maven-dependency-submission-action",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "Submit Maven dependencies to GitHub dependency submission API",
   "main": "index.js",
   "scripts": {
@@ -34,7 +34,7 @@
     "@yao-pkg/pkg": "^5.11.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3",
-    "vitest": "^1.2.1"
+    "vitest": "^1.6.1"
   },
   "bin": {
     "cli": "lib/src/executable/cli.js"

src/depgraph.test.ts

@@ -116,6 +116,25 @@ describe('depgraph', () => {
       });
     });
 
+    describe('cycle-tree', () => {
+      let depGraph;
+      beforeAll(() => {
+        depGraph = parseDependencyJson(getTestDataFile("cycle-tree"));
+      });
+
+      it('should parse out the top level dependencies', () => {
+        const mavenDependencies = new MavenDependencyGraph(depGraph);
+        expect(mavenDependencies.getPackageCount()).to.equal(3);
+      });
+
+      it('should be able to generate a manifest despite having a cycle', () => {
+        const mavenDependencies = new MavenDependencyGraph(depGraph);
+        const manifest = mavenDependencies.createManifest();
+
+        expect(manifest.name).to.equal('hadoop-main');
+        expect(manifest.countDependencies()).to.equal(2);
+      })
+    });
 
     describe('bs-parent-dep-tree', () => {
 

src/depgraph.ts

@@ -85,13 +85,19 @@ export class MavenDependencyGraph {
       let scope = getDependencyScopeForMavenScope(artifact.scopes);
       manifest.addDirectDependency(depPackage, scope);
 
-      function addTransitiveDeps(dependencies) {
+      function addTransitiveDeps(dependencies, seen: Set<string> = new Set()) {
         if (dependencies) {
           dependencies.forEach(transitiveDep => {
-            const transitiveDepArtifact = packageUrlToArtifact[transitiveDep.packageURL.toString()];
+            let purl = transitiveDep.packageURL.toString();
+            if (seen.has(purl)) {
+              // we're in a cycle! skip this one.
+              return;
+            }
+            const transitiveDepArtifact = packageUrlToArtifact[purl];
             const transitiveDepScope = getDependencyScopeForMavenScope(transitiveDepArtifact.scopes);
             manifest.addIndirectDependency(transitiveDep, transitiveDepScope);
-            addTransitiveDeps(transitiveDep.dependencies);
+            seen.add(purl);
+            addTransitiveDeps(transitiveDep.dependencies, seen);
           });
         }
       }

src/index.ts

@@ -18,6 +18,10 @@ async function run() {
       sha: core.getInput('snapshot-sha'),
       ref: core.getInput('snapshot-ref'),
     }
+    const correlator = core.getInput('correlator');
+    if (correlator) {
+      snapshotConfig.correlator = correlator;
+    }
     const detectorName = core.getInput('detector-name');
     if (detectorName !== '') {
       snapshotConfig.detector = {

src/snapshot-generator.test.ts

@@ -68,5 +68,30 @@ describe('snapshot-generator', () => {
       expect(snapshot.detector.version).toBe(version);
       expect(snapshot.manifests['problem-dependency-graph-2602'].countDependencies()).toBe(230);
     }, 40000);
+
+    it('should use correlator from snapshotConfig if it exists', async() => {
+      const projectDir = getMavenProjectDirectory('simple');
+      const snapshotConfig = {
+        correlator: 'configCorrelator',
+        job: {
+          correlator: 'jobCorrelator'
+        }
+      };
+      const snapshot = await generateSnapshot(projectDir, undefined, snapshotConfig);
+
+      expect(snapshot.job.correlator).toBe('configCorrelator');
+    }, 20000);
+
+    it('should use a default job correlator when not specified', async() => {
+      const projectDir = getMavenProjectDirectory('simple');
+      const snapshotConfig = {
+        job: {
+          correlator: 'jobCorrelator'
+        }
+      };
+      const snapshot = await generateSnapshot(projectDir, undefined, snapshotConfig);
+
+      expect(snapshot.job.correlator).toBe('jobCorrelator');
+    }, 20000);
   });
 });

src/snapshot-generator.ts

@@ -7,7 +7,7 @@ import { MavenRunner } from './maven-runner';
 import { loadFileContents } from './utils/file-utils';
 
 const packageData = require('../package.json');
-const DEPGRAPH_MAVEN_PLUGIN_VERSION = '4.0.2';
+const DEPGRAPH_MAVEN_PLUGIN_VERSION = '4.0.3';
 
 export type MavenConfiguration = {
   ignoreMavenWrapper?: boolean;
@@ -27,6 +27,7 @@ export type SnapshotConfig = {
     url: string;
     version: string;
   };
+  correlator?: string;
 };
 
 export async function generateSnapshot(directory: string, mvnConfig?: MavenConfiguration, snapshotConfig?: SnapshotConfig) {
@@ -53,12 +54,16 @@ export async function generateSnapshot(directory: string, mvnConfig?: MavenConfi
     const snapshot = new Snapshot(detector, snapshotConfig?.context, snapshotConfig?.job);
     snapshot.addManifest(manifest);
 
-    const specifiedRef = getNonEmtptyValue(snapshotConfig?.ref);
+    snapshot.job.correlator = snapshotConfig?.correlator
+      ? snapshotConfig.correlator
+      : snapshot.job?.correlator;
+
+    const specifiedRef = getNonEmptyValue(snapshotConfig?.ref);
     if (specifiedRef) {
       snapshot.ref = specifiedRef;
     }
 
-    const specifiedSha = getNonEmtptyValue(snapshot?.sha);
+    const specifiedSha = getNonEmptyValue(snapshot?.sha);
     if (specifiedSha) {
       snapshot.sha = specifiedSha;
     }
@@ -168,7 +173,7 @@ function getRepositoryRelativePath(file) {
   return result;
 }
 
-function getNonEmtptyValue(str?: string) {
+function getNonEmptyValue(str?: string) {
   if (str) {
     const trimmed = str.trim();
     if (trimmed.length > 0) {

test-data/dependency-trees/cycle-tree.json

@@ -0,0 +1,57 @@
+{
+  "graphName" : "hadoop-main",
+  "artifacts" : [ {
+    "id" : "org.apache.hadoop:hadoop-annotations:jar:compile",
+    "numericId" : 1,
+    "groupId" : "org.apache.hadoop",
+    "artifactId" : "hadoop-annotations",
+    "version" : "3.5.0-SNAPSHOT",
+    "optional" : false,
+    "scopes" : [ "compile" ],
+    "types" : [ "jar" ]
+  }, {
+    "id" : "jdiff:jdiff:jar:provided",
+    "numericId" : 2,
+    "groupId" : "jdiff",
+    "artifactId" : "jdiff",
+    "version" : "1.0.9",
+    "optional" : false,
+    "scopes" : [ "provided" ],
+    "types" : [ "jar" ]
+  }, {
+    "id" : "org.apache.hadoop:hadoop-project-dist:pom:compile",
+    "numericId" : 3,
+    "groupId" : "org.apache.hadoop",
+    "artifactId" : "hadoop-project-dist",
+    "version" : "3.5.0-SNAPSHOT",
+    "optional" : false,
+    "scopes" : [ "compile" ],
+    "types" : [ "pom" ]
+  } ],
+  "dependencies" : [ {
+    "from" : "org.apache.hadoop:hadoop-annotations:jar:compile",
+    "to" : "jdiff:jdiff:jar:provided",
+    "numericFrom" : 1,
+    "numericTo" : 2,
+    "resolution" : "INCLUDED"
+  }, {
+    "from" : "org.apache.hadoop:hadoop-annotations:jar:compile",
+    "to" : "jdiff:jdiff:jar:provided",
+    "numericFrom" : 1,
+    "numericTo" : 3,
+    "resolution" : "INCLUDED"
+  }, {
+    "from" : "jdiff:jdiff:jar:provided",
+    "to" : "org.apache.hadoop:hadoop-project-dist:pom:compile",
+    "numericFrom" : 2,
+    "numericTo" : 3,
+    "resolution" : "INCLUDED"
+  }, {
+    "from" : "org.apache.hadoop:hadoop-project-dist:pom:compile",
+    "to" : "jdiff:jdiff:jar:provided",
+    "numericFrom" : 3,
+    "numericTo" : 2,
+    "resolution" : "INCLUDED"
+  }
+]
+}