Merge pull request #56 from snyk/chore/add-output-comments

chore: comment the workflow output return data

Author: bsalomon-snyk

internal/commands/ostest/depgraph_flow.go

@@ -103,11 +103,11 @@ func testAllDepGraphs(
 	return allLegacyFindings, allOutputData, nil
 }
 
+// createTestSubject creates a test subject from a depGraph and display target file.
 func createTestSubject(
 	depGraph *testapi.IoSnykApiV1testdepgraphRequestDepGraph,
 	displayTargetFile string,
 ) (testapi.TestSubjectCreate, error) {
-	// Create depgraph subject
 	depGraphSubject := testapi.DepGraphSubjectCreate{
 		Type:     testapi.DepGraphSubjectCreateTypeDepGraph,
 		DepGraph: *depGraph,
@@ -117,7 +117,6 @@ func createTestSubject(
 		},
 	}
 
-	// Create test subject with depgraph
 	var subject testapi.TestSubjectCreate
 	err := subject.FromDepGraphSubjectCreate(depGraphSubject)
 	if err != nil {
@@ -140,6 +139,10 @@ func getProjectName(
 	return projectName
 }
 
+// handleOutput processes both legacy JSON and human-readable findings into their respective outputs.
+// Human-readable output is processed by the local template renderer.
+// JSON file output is written to file here, while JSON stdout is added to the output workflow.
+// Summary data is added to the output workflow for exit code calculation.
 func handleOutput(
 	ictx workflow.InvocationContext,
 	allLegacyFindings []definitions.LegacyVulnerabilityResponse,
@@ -198,6 +201,7 @@ func handleOutput(
 	return finalOutput, nil
 }
 
+// prepareJSONOutput prepares legacy JSON output from findings.
 func prepareJSONOutput(
 	allLegacyFindings []definitions.LegacyVulnerabilityResponse,
 	errFactory *errors.ErrorFactory,

internal/commands/ostest/test_execution.go

@@ -32,6 +32,7 @@ const LogFieldCount = "count"
 var ErrNoSummaryData = std_errors.New("no summary data to create")
 
 // RunTest executes the common test flow with the provided test subject.
+// Returns legacy JSON and/or human-readable workflow data, depending on parameters.
 func RunTest(
 	ctx context.Context,
 	ictx workflow.InvocationContext,
@@ -155,7 +156,10 @@ func executeTest(
 	return finalResult, findingsData, nil
 }
 
-// prepareOutput prepares the workflow data for output.
+// prepareOutput prepares raw test result findings into data for the output workflow.
+// If JSON is requested (either to file or stdout), it generates legacy JSON findings.
+// If JSON-stdout is not requested, then human-readable findings are added to the output workflow.
+// Human-readable stdout with JSON file output is a valid combination and returns both human-readable and legacy JSON types.
 func prepareOutput(
 	ictx workflow.InvocationContext,
 	findingsData []testapi.FindingData,