adding nice error reporting. working on summary files

.github/shared/src/error-reporting.js

@@ -0,0 +1,34 @@
+// @ts-check
+import * as fs from "fs";
+import { consoleLogger } from "./logger.js";
+
+/**
+ * Set the summary of the github step summary for a job. This feature is intended for formatted markdown,
+ * which can be used to display the results of a job in a more readable format.
+ *
+ * Format your results as a markdown table and go to town!
+ * @param {string} content
+ * @returns {void}
+ */
+export function setSummary(content) {
+    if (!process.env.GITHUB_STEP_SUMMARY) {
+        consoleLogger.info("GITHUB_STEP_SUMMARY is not set. Skipping summary update.");
+        return;
+    }
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+
+    fs.writeFileSync(summaryFile, content);
+}
+
+/**
+ * This function is used to ask the github agent to annotate a file in a github PR with an error message.
+ * @param {string} repoPath
+ * @param {string} line
+ * @param {string} col
+ * @param {string} message
+ * @returns {void}
+ */
+export function annotateFileError(repoPath, line, col, message) {
+    const errorLine = `::error file=${repoPath},line=${line},col=${col}::${message}`;
+    consoleLogger.info(errorLine);
+}

eng/tools/oav-runner/src/formatting.ts

@@ -1,3 +1,12 @@
+
+export interface ReportableOavError {
+  message: string;
+  file: string;
+  line?: number;  // we don't always have a line or column if the spec is invalid
+  column?: number;
+}
+
+
 // todo: come up with a better type for this
 export function outputAnnotatedErrors(errors: Array<object>){
   // echo "::error file=src/app.js,line=42,col=13::Something went wrong here"
@@ -13,4 +22,5 @@ export function outputSummaryReport(targetDirectory: string, errors: Array<objec
       >> $GITHUB_STEP_SUMMARY
   */
     console.log(`outputting ${errors} to summary report to ${targetDirectory}`);
-}
+}
+

eng/tools/oav-runner/src/main.ts

@@ -7,12 +7,14 @@ import * as path from 'path';
 // import * as glob from 'glob';
 import * as fs from 'fs';
 
+import { consoleLogger } from '@azure-tools/specs-shared/logger';
 import { getChangedFiles, swagger } from "@azure-tools/specs-shared/changed-files";
+import { ReportableOavError } from './formatting.js';
 
-export async function checkSpecs(rootDirectory: string): Promise<[number, Array<object>]> {
-    let errors: Array<object> = [];
+export async function checkSpecs(rootDirectory: string): Promise<[number, Array<ReportableOavError>]> {
+    let errors: Array<ReportableOavError> = [];
 
-    console.log(`Executing checks in ${rootDirectory}`);
+    consoleLogger.info(`Executing checks in ${rootDirectory}`);
 
     const changedFiles = await getChangedFiles({
       cwd: rootDirectory
@@ -23,14 +25,29 @@ export async function checkSpecs(rootDirectory: string): Promise<[number, Array<
     for (const swaggerFile of swaggerFiles) {
       try {
         const errorResults = await oav.validateSpec(swaggerFile, undefined);
-
         if (errorResults.validateSpec && errorResults.validateSpec.errors){
-          errors.push(errorResults.validateSpec.errors);
+          for(const error of errorResults.validateSpec.errors) {
+            errors.push( {
+              message: `${error.code}: ${error.message}`,
+              file: swaggerFile,
+              line: error.position?.line,
+              column: error.position?.column
+            } as ReportableOavError);
+          }
         }
       }
       catch (e) {
-        // todo: add error handling beyond logging
-        console.log(e);
+        if (e instanceof Error) {
+          errors.push( {
+            message: e.message,
+            file: swaggerFile
+          } as ReportableOavError);
+        } else {
+          errors.push( {
+            message: `Unhandled error validating ${swaggerFile}: ${e}`,
+            file: swaggerFile
+          } as ReportableOavError);
+        }
       }
     }
 
@@ -64,9 +81,9 @@ export async function processFilesToSpecificationList(rootDirectory: string, fil
           return false;
         }
 
-        let swaggerResult = swagger(file);
-        let targetFile = path.join(rootDirectory, file);
-        console.log(`Checking ${targetFile}`);
+        const swaggerResult = swagger(file);
+        const targetFile = path.join(rootDirectory, file);
+        consoleLogger.info(`Checking ${targetFile}`);
 
         // if it's a swagger file, we should check to see if it exists
         // as a deleted file will also show up in the changed files list