Refactor: Include filename when generating markdown

Author: shati-patel

extensions/ql-vscode/src/remote-queries/remote-queries-markdown-generation.ts

@@ -8,8 +8,10 @@ import { AnalysisAlert, AnalysisRawResults, AnalysisResults, CodeSnippet, FileLi
 
 export type MarkdownLinkType = 'local' | 'gist';
 
-// Each array item is a line of the markdown file.
-export type MarkdownFile = string[];
+export interface MarkdownFile {
+  fileName: string;
+  content: string[]; // Each array item is a line of the markdown file.
+}
 
 /**
  * Generates markdown files with variant analysis results.
@@ -19,9 +21,9 @@ export function generateMarkdown(
   analysesResults: AnalysisResults[],
   linkType: MarkdownLinkType
 ): MarkdownFile[] {
-  const files: MarkdownFile[] = [];
+  const resultsFiles: MarkdownFile[] = [];
   // Generate summary file with links to individual files
-  const summaryLines: MarkdownFile = generateMarkdownSummary(query);
+  const summaryFile: MarkdownFile = generateMarkdownSummary(query);
   for (const analysisResult of analysesResults) {
     const resultsCount = getAnalysisResultCount(analysisResult);
     if (resultsCount === 0) {
@@ -30,29 +32,33 @@ export function generateMarkdown(
 
     // Append nwo and results count to the summary table
     const nwo = analysisResult.nwo;
-    const link = createRelativeLink(nwo, linkType);
-    summaryLines.push(`| ${nwo} | [${resultsCount} result(s)](${link}) |`);
+    const fileName = createFileName(nwo);
+    const link = createRelativeLink(fileName, linkType);
+    summaryFile.content.push(`| ${nwo} | [${resultsCount} result(s)](${link}) |`);
 
     // Generate individual markdown file for each repository
-    const lines = [
+    const resultsFileContent = [
       `### ${analysisResult.nwo}`,
       ''
     ];
     for (const interpretedResult of analysisResult.interpretedResults) {
       const individualResult = generateMarkdownForInterpretedResult(interpretedResult, query.language);
-      lines.push(...individualResult);
+      resultsFileContent.push(...individualResult);
     }
     if (analysisResult.rawResults) {
       const rawResultTable = generateMarkdownForRawResults(analysisResult.rawResults);
-      lines.push(...rawResultTable);
+      resultsFileContent.push(...rawResultTable);
     }
-    files.push(lines);
+    resultsFiles.push({
+      fileName: fileName,
+      content: resultsFileContent,
+    });
   }
-  return [summaryLines, ...files];
+  return [summaryFile, ...resultsFiles];
 }
 
 export function generateMarkdownSummary(query: RemoteQuery): MarkdownFile {
-  const lines: MarkdownFile = [];
+  const lines: string[] = [];
   // Title
   lines.push(
     `### Results for "${query.queryName}"`,
@@ -83,11 +89,14 @@ export function generateMarkdownSummary(query: RemoteQuery): MarkdownFile {
     '| --- | --- |',
   );
   // nwo and result count will be appended to this table
-  return lines;
+  return {
+    fileName: 'summary.md',
+    content: lines
+  };
 }
 
-function generateMarkdownForInterpretedResult(interpretedResult: AnalysisAlert, language: string): MarkdownFile {
-  const lines: MarkdownFile = [];
+function generateMarkdownForInterpretedResult(interpretedResult: AnalysisAlert, language: string): string[] {
+  const lines: string[] = [];
   lines.push(createMarkdownRemoteFileRef(
     interpretedResult.fileLink,
     interpretedResult.highlightedRegion?.startLine,
@@ -123,8 +132,8 @@ function generateMarkdownForCodeSnippet(
   codeSnippet: CodeSnippet,
   language: string,
   highlightedRegion?: HighlightedRegion
-): MarkdownFile {
-  const lines: MarkdownFile = [];
+): string[] {
+  const lines: string[] = [];
   const snippetStartLine = codeSnippet.startLine || 0;
   const codeLines = codeSnippet.text
     .split('\n')
@@ -183,11 +192,11 @@ function generateMarkdownForAlertMessage(
 function generateMarkdownForPathResults(
   interpretedResult: AnalysisAlert,
   language: string
-): MarkdownFile {
-  const lines: MarkdownFile = [];
+): string[] {
+  const lines: string[] = [];
   lines.push('#### Paths', '');
   for (const codeFlow of interpretedResult.codeFlows) {
-    const pathLines: MarkdownFile = [];
+    const pathLines: string[] = [];
     const stepCount = codeFlow.threadFlows.length;
     const title = `Path with ${stepCount} steps`;
     for (let i = 0; i < stepCount; i++) {
@@ -215,8 +224,8 @@ function generateMarkdownForPathResults(
 
 function generateMarkdownForRawResults(
   analysisRawResults: AnalysisRawResults
-): MarkdownFile {
-  const tableRows: MarkdownFile = [];
+): string[] {
+  const tableRows: string[] = [];
   const columnCount = analysisRawResults.schema.columns.length;
   // Table headers are the column names if they exist, and empty otherwise
   const headers = analysisRawResults.schema.columns.map(
@@ -282,8 +291,8 @@ export function createMarkdownRemoteFileRef(
  * 
  * </details>
  */
-function buildExpandableMarkdownSection(title: string, contents: MarkdownFile): MarkdownFile {
-  const expandableLines: MarkdownFile = [];
+function buildExpandableMarkdownSection(title: string, contents: string[]): string[] {
+  const expandableLines: string[] = [];
   expandableLines.push(
     '<details>',
     `<summary>${title}</summary>`,
@@ -296,18 +305,23 @@ function buildExpandableMarkdownSection(title: string, contents: MarkdownFile):
   return expandableLines;
 }
 
-function createRelativeLink(nwo: string, linkType: MarkdownLinkType): string {
-  const [owner, repo] = nwo.split('/');
-
+function createRelativeLink(fileName: string, linkType: MarkdownLinkType): string {
   switch (linkType) {
     case 'local':
-      return `./${owner}-${repo}.md`;
+      return `./${fileName}.md`;
 
     case 'gist':
-      // Creates anchor link to a file in the gist. This is of the form:
+      // Creates an anchor link to a file in the gist. This is of the form:
       // '#file-<name>-<file-extension>'
-      // 
-      // TODO: Make sure these names align with the actual file names once we upload them to a gist.
-      return `#file-${owner}-${repo}-md`;
+      return `#file-${fileName}-md`;
   }
 }
+
+/**
+ * Creates the name of the markdown file for a given repository nwo.
+ * This name doesn't include the file extension.
+ */
+function createFileName(nwo: string) {
+  const [owner, repo] = nwo.split('/');
+  return `${owner}-${repo}`;
+}

extensions/ql-vscode/test/pure-tests/remote-queries/markdown-generation/markdown-generation.test.ts

@@ -27,9 +27,9 @@ describe('markdown generation', async function() {
       const expectedTestOutput2 = await readTestOutputFile('data/interpreted-results/path-problem/results-repo2.md');
 
       // Check that markdown output is correct, after making line endings consistent
-      expect(markdownFile0.join('\n')).to.equal(expectedSummaryFile);
-      expect(markdownFile1.join('\n')).to.equal(expectedTestOutput1);
-      expect(markdownFile2.join('\n')).to.equal(expectedTestOutput2);
+      expect(markdownFile0.content.join('\n')).to.equal(expectedSummaryFile);
+      expect(markdownFile1.content.join('\n')).to.equal(expectedTestOutput1);
+      expect(markdownFile2.content.join('\n')).to.equal(expectedTestOutput2);
     });
   });
 
@@ -56,9 +56,9 @@ describe('markdown generation', async function() {
       const expectedTestOutput2 = await readTestOutputFile('data/interpreted-results/problem/results-repo2.md');
 
       // Check that markdown output is correct, after making line endings consistent
-      expect(markdownFile0.join('\n')).to.equal(expectedSummaryFile);
-      expect(markdownFile1.join('\n')).to.equal(expectedTestOutput1);
-      expect(markdownFile2.join('\n')).to.equal(expectedTestOutput2);
+      expect(markdownFile0.content.join('\n')).to.equal(expectedSummaryFile);
+      expect(markdownFile1.content.join('\n')).to.equal(expectedTestOutput1);
+      expect(markdownFile2.content.join('\n')).to.equal(expectedTestOutput2);
     });
   });
 
@@ -85,9 +85,9 @@ describe('markdown generation', async function() {
       const expectedTestOutput2 = await readTestOutputFile('data/raw-results/results-repo2.md');
 
       // Check that markdown output is correct, after making line endings consistent
-      expect(markdownFile0.join('\n')).to.equal(expectedSummaryFile);
-      expect(markdownFile1.join('\n')).to.equal(expectedTestOutput1);
-      expect(markdownFile2.join('\n')).to.equal(expectedTestOutput2);
+      expect(markdownFile0.content.join('\n')).to.equal(expectedSummaryFile);
+      expect(markdownFile1.content.join('\n')).to.equal(expectedTestOutput1);
+      expect(markdownFile2.content.join('\n')).to.equal(expectedTestOutput2);
     });
   });
 });