Merge pull request #188 from snyk/feat/ZEN-668/add-scm-report-test-su…

…pport

README.md

@@ -116,6 +116,25 @@ const results = await codeClient.analyzeFolders({
 });
 ```
 
+### Run analysis and report results to platform
+
+```javascript
+const results = await codeClient.analyzeFolders({
+  connection: { baseURL, sessionToken, source },
+  analysisOptions: {
+    severity: 1,
+  },
+  fileOptions: {
+    paths: ['/home/user/repo'],
+    symlinksEnabled: false,
+  },
+  reportOptions: {
+    enabled: true,
+    projectName: 'example-project',
+  },
+});
+```
+
 ### Creates a new bundle based on a previously uploaded one
 
 ```javascript
@@ -129,6 +148,21 @@ const results = await codeClient.extendAnalysis({
 
 ```
 
+### Run analysis on an existing SCM project and report results to platform
+
+```javascript
+const results = await codeClient.analyzeScmProject({
+  connection: { baseURL, sessionToken, source },
+  analysisOptions: {
+    severity: 1,
+  },
+  reportOptions: {
+    projectId: '<Snyk Project UUID>',
+    commitId: '<Commit SHA to scan>',
+  },
+});
+```
+
 ### Errors
 
 If there are any errors the result of every call will contain the following:

package.json

@@ -64,6 +64,7 @@
     "jest": "^26.4.2",
     "jest-extended": "^0.8.0",
     "jsonschema": "^1.2.11",
+    "nock": "^13.3.2",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.1.1",
     "ts-jest": "^26.3.0",

src/analysis.ts

@@ -12,9 +12,10 @@ import {
   GetAnalysisResponseDto,
   AnalysisFailedResponse,
   GetAnalysisOptions,
+  ConnectionOptions,
 } from './http';
 import { createBundleFromFolders, remoteBundleFactory } from './bundles';
-import { reportBundle } from './report';
+import { reportBundle, reportScm } from './report';
 import { emitter } from './emitter';
 import {
   AnalysisResult,
@@ -23,12 +24,27 @@ import {
   AnalysisFiles,
   Suggestion,
   ReportUploadResult,
+  ScmAnalysis,
 } from './interfaces/analysis-result.interface';
-import { FileAnalysisOptions, ReportOptions } from './interfaces/analysis-options.interface';
+import { AnalysisContext, FileAnalysisOptions, ScmAnalysisOptions } from './interfaces/analysis-options.interface';
 import { FileAnalysis } from './interfaces/files.interface';
 
 const sleep = (duration: number) => new Promise(resolve => setTimeout(resolve, duration));
 
+function getConnectionOptions(connectionOptions: ConnectionOptions): ConnectionOptions {
+  return {
+    ...connectionOptions,
+    // Ensure requestId is set.
+    requestId: connectionOptions.requestId ?? uuidv4(),
+  };
+}
+
+function getAnalysisContext(
+  analysisContext: AnalysisContext['analysisContext'] | undefined,
+): AnalysisContext | Record<string, never> {
+  return analysisContext ? { analysisContext } : {};
+}
+
 async function pollAnalysis(
   options: GetAnalysisOptions,
 ): Promise<Result<AnalysisFailedResponse | AnalysisResult, GetAnalysisErrorCodes>> {
@@ -92,23 +108,27 @@ function normalizeResultFiles(files: AnalysisFiles, baseDir: string): AnalysisFi
   }, {});
 }
 
+/**
+ * Perform a file-based analysis.
+ * Optionally with reporting of results to the platform.
+ */
 export async function analyzeFolders(options: FileAnalysisOptions): Promise<FileAnalysis | null> {
-  if (!options.connection.requestId) {
-    options.connection.requestId = uuidv4();
-  }
+  const connectionOptions = getConnectionOptions(options.connection);
+  const analysisContext = getAnalysisContext(options.analysisContext);
+
   const fileBundle = await createBundleFromFolders({
-    ...options.connection,
+    ...connectionOptions,
     ...options.fileOptions,
     languages: options.languages,
   });
   if (fileBundle === null) return null;
 
   const config = {
     bundleHash: fileBundle.bundleHash,
-    ...options.connection,
+    ...connectionOptions,
     ...options.analysisOptions,
     shard: calcHash(fileBundle.baseDir),
-    ...(options.analysisContext ? { analysisContext: options.analysisContext } : {}),
+    ...analysisContext,
   };
 
   let analysisResults: AnalysisResult;
@@ -330,3 +350,21 @@ export async function extendAnalysis(options: FileAnalysis & { files: string[] }
 
   return { ...options, fileBundle, analysisResults };
 }
+
+/**
+ * Perform an SCM-based analysis for an existing project,
+ * with reporting of results to the platform.
+ */
+export async function analyzeScmProject(options: ScmAnalysisOptions): Promise<ScmAnalysis | null> {
+  const connectionOptions = getConnectionOptions(options.connection);
+  const analysisContext = getAnalysisContext(options.analysisContext);
+
+  const { analysisResult: analysisResults, uploadResult: reportResults } = await reportScm({
+    ...connectionOptions,
+    ...options.analysisOptions,
+    ...options.reportOptions,
+    ...analysisContext,
+  });
+
+  return { analysisResults, reportResults };
+}

src/http.ts

@@ -8,7 +8,12 @@ import { ErrorCodes, GenericErrorTypes, DEFAULT_ERROR_MESSAGES, MAX_RETRY_ATTEMP
 import { BundleFiles, SupportedFiles } from './interfaces/files.interface';
 import { AnalysisResult, ReportResult } from './interfaces/analysis-result.interface';
 import { FailedResponse, makeRequest, Payload } from './needle';
-import { AnalysisOptions, AnalysisContext, ReportOptions } from './interfaces/analysis-options.interface';
+import {
+  AnalysisOptions,
+  AnalysisContext,
+  ReportOptions,
+  ScmReportOptions,
+} from './interfaces/analysis-options.interface';
 
 type ResultSuccess<T> = { type: 'success'; value: T };
 type ResultError<E> = {
@@ -32,6 +37,7 @@ export interface ConnectionOptions {
 }
 
 // The trick to typecast union type alias
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function isSubsetErrorCode<T>(code: any, messages: { [c: number]: string }): code is T {
   if (code in messages) {
     return true;
@@ -98,6 +104,10 @@ export function startSession(options: StartSessionOptions): StartSessionResponse
   };
 }
 
+export function getVerifyCallbackUrl(authHost: string): string {
+  return `${authHost}/api/verify/callback`;
+}
+
 export type IpFamily = 6 | undefined;
 /**
  * Dispatches a FORCED IPv6 request to test client's ISP and network capability.
@@ -403,19 +413,27 @@ const REPORT_ERROR_MESSAGES: { [P in ReportErrorCodes]: string } = {
 export interface UploadReportOptions extends GetAnalysisOptions {
   report: ReportOptions;
 }
+
+export interface ScmUploadReportOptions extends ConnectionOptions, AnalysisOptions, AnalysisContext, ScmReportOptions {}
+
 export interface GetReportOptions extends ConnectionOptions {
-  reportId: string;
+  pollId: string;
 }
 
 export type InitUploadResponseDto = {
   reportId: string;
 };
 
+export type InitScmUploadResponseDto = {
+  testId: string;
+};
+
 export type UploadReportResponseDto = ReportResult | AnalysisFailedResponse | AnalysisResponseProgress;
 
-export async function initReport(
-  options: UploadReportOptions,
-): Promise<Result<InitUploadResponseDto, ReportErrorCodes>> {
+/**
+ * Trigger a file-based test with reporting.
+ */
+export async function initReport(options: UploadReportOptions): Promise<Result<string, ReportErrorCodes>> {
   const config: Payload = {
     headers: {
       ...commonHttpHeaders(options),
@@ -440,16 +458,19 @@ export async function initReport(
   };
 
   const res = await makeRequest<InitUploadResponseDto>(config);
-  if (res.success) return { type: 'success', value: res.body };
+  if (res.success) return { type: 'success', value: res.body.reportId };
   return generateError<ReportErrorCodes>(res.errorCode, REPORT_ERROR_MESSAGES, 'initReport');
 }
 
+/**
+ * Retrieve a file-based test with reporting.
+ */
 export async function getReport(options: GetReportOptions): Promise<Result<UploadReportResponseDto, ReportErrorCodes>> {
   const config: Payload = {
     headers: {
       ...commonHttpHeaders(options),
     },
-    url: `${options.baseURL}/report/${options.reportId}`,
+    url: `${options.baseURL}/report/${options.pollId}`,
     method: 'get',
   };
 
@@ -458,6 +479,45 @@ export async function getReport(options: GetReportOptions): Promise<Result<Uploa
   return generateError<ReportErrorCodes>(res.errorCode, REPORT_ERROR_MESSAGES, 'getReport', res.error?.message);
 }
 
-export function getVerifyCallbackUrl(authHost: string): string {
-  return `${authHost}/api/verify/callback`;
+/**
+ * Trigger an SCM-based test with reporting.
+ */
+export async function initScmReport(options: ScmUploadReportOptions): Promise<Result<string, ReportErrorCodes>> {
+  const config: Payload = {
+    headers: {
+      ...commonHttpHeaders(options),
+    },
+    url: `${options.baseURL}/test`,
+    method: 'post',
+    body: {
+      workflowData: {
+        projectId: options.projectId,
+        commitHash: options.commitId,
+      },
+      ...pick(options, ['severity', 'prioritized', 'analysisContext']),
+    },
+  };
+
+  const res = await makeRequest<InitScmUploadResponseDto>(config);
+  if (res.success) return { type: 'success', value: res.body.testId };
+  return generateError<ReportErrorCodes>(res.errorCode, REPORT_ERROR_MESSAGES, 'initReport');
+}
+
+/**
+ * Fetch an SCM-based test with reporting.
+ */
+export async function getScmReport(
+  options: GetReportOptions,
+): Promise<Result<UploadReportResponseDto, ReportErrorCodes>> {
+  const config: Payload = {
+    headers: {
+      ...commonHttpHeaders(options),
+    },
+    url: `${options.baseURL}/test/${options.pollId}`,
+    method: 'get',
+  };
+
+  const res = await makeRequest<UploadReportResponseDto>(config);
+  if (res.success) return { type: 'success', value: res.body };
+  return generateError<ReportErrorCodes>(res.errorCode, REPORT_ERROR_MESSAGES, 'getReport', res.error?.message);
 }

src/index.ts

@@ -1,4 +1,4 @@
-import { analyzeFolders, extendAnalysis } from './analysis';
+import { analyzeFolders, extendAnalysis, analyzeScmProject } from './analysis';
 import { getSupportedFiles, createBundleFromFolders, createBundleWithCustomFiles } from './bundles';
 import { emitter } from './emitter';
 import { startSession, checkSession, getAnalysis, getIpFamily, IpFamily } from './http';
@@ -17,11 +17,13 @@ import {
   Suggestion,
   Marker,
   ReportResult,
+  ScmAnalysis,
 } from './interfaces/analysis-result.interface';
 
 export {
   getGlobPatterns,
   analyzeFolders,
+  analyzeScmProject,
   getSupportedFiles,
   createBundleFromFolders,
   createBundleWithCustomFiles,
@@ -46,4 +48,5 @@ export {
   IpFamily,
   AnalysisContext,
   ReportResult,
+  ScmAnalysis,
 };

src/interfaces/analysis-options.interface.ts

@@ -60,10 +60,21 @@ export interface ReportOptions {
   remoteRepoUrl?: string;
 }
 
+export interface ScmReportOptions {
+  projectId?: string;
+  commitId?: string;
+}
+
 export interface FileAnalysisOptions extends AnalysisContext {
   connection: ConnectionOptions;
   analysisOptions: AnalysisOptions;
   fileOptions: AnalyzeFoldersOptions;
   reportOptions?: ReportOptions;
   languages?: string[];
 }
+
+export interface ScmAnalysisOptions extends AnalysisContext {
+  connection: ConnectionOptions;
+  analysisOptions: AnalysisOptions;
+  reportOptions: ScmReportOptions;
+}

src/interfaces/analysis-result.interface.ts

@@ -99,3 +99,8 @@ export interface ReportResult {
 }
 
 export type AnalysisResult = AnalysisResultSarif | AnalysisResultLegacy;
+
+export interface ScmAnalysis {
+  analysisResults: AnalysisResultSarif;
+  reportResults?: ReportUploadResult;
+}