Transformations: Add transformation builder tests and refactor (#83285)

* baldm0mma/script_tests/ update jest.config paths

* baldm0mma/script_tests/ refactor makefile content

* baldm0mma/script_tests/ refactor file write commands

* baldm0mma/script_tests/ create test module

* baldm0mma/script_tests/ add to codeowners

* baldm0mma/script_tests/ recenter content

* baldm0mma/script_tests/ create buildMarkdownContent and update whitespace

* baldm0mma/script_tests/ run build script

* baldm0mma/script_tests/ update tests to remove make dep and node dep

* baldm0mma/script_tests/ update cntent

* baldm0mma/script_tests/ update makefile

* baldm0mma/script_tests/ update buildMarkdownContent

* baldm0mma/script_tests/ remove unused imports

* baldm0mma/script_tests/ update test annotation

* baldm0mma/script_tests/ prettier

* baldm0mma/script_tests/ update tests

* baldm0mma/script_tests/ update content

* baldm0mma/script_tests/ update annos

* baldm0mma/script_tests/ remove unused vars

* baldm0mma/script_tests/ remove unused imports

* baldm0mma/script_tests/ update annos

* baldm0mma/script_tests/ update paths

* Update scripts/docs/generate-transformations.test.ts

Co-authored-by: Jack Baldry <jack.baldry@grafana.com>

* baldm0mma/script_tests/ update comment

---------

Co-authored-by: Jack Baldry <jack.baldry@grafana.com>

.github/CODEOWNERS

@@ -530,7 +530,7 @@ playwright.config.ts @grafana/plugins-platform-frontend
 /scripts/generate-icon-bundle.js @grafana/plugins-platform-frontend @grafana/grafana-frontend-platform
 /scripts/levitate-parse-json-report.js @grafana/plugins-platform-frontend
 
-/scripts/docs/generate-transformations.ts @grafana/dataviz-squad
+/scripts/docs/generate-transformations* @grafana/dataviz-squad
 /scripts/webpack/ @grafana/frontend-ops
 /scripts/generate-a11y-report.sh @grafana/grafana-frontend-platform
 .pa11yci.conf.js @grafana/grafana-frontend-platform

docs/Makefile

@@ -9,7 +9,6 @@ include docs.mk
 
 .PHONY: sources/panels-visualizations/query-transform-data/transform-data/index.md
 sources/panels-visualizations/query-transform-data/transform-data/index.md: ## Generate the Transform Data page source.
-sources/panels-visualizations/query-transform-data/transform-data/index.md:
 	cd $(CURDIR)/.. && npx tsc ./scripts/docs/generate-transformations.ts && \
-	node ./scripts/docs/generate-transformations.js > $(CURDIR)/$@ && \
+	node -e "require('./scripts/docs/generate-transformations').buildMarkdownContent()" && \
 	npx prettier -w $(CURDIR)/$@

jest.config.js

@@ -30,7 +30,7 @@ module.exports = {
     `/node_modules/(?!${esModules})`, // exclude es modules to prevent TS complaining
   ],
   moduleDirectories: ['public', 'node_modules'],
-  roots: ['<rootDir>/public/app', '<rootDir>/public/test', '<rootDir>/packages'],
+  roots: ['<rootDir>/public/app', '<rootDir>/public/test', '<rootDir>/packages', '<rootDir>/scripts'],
   testRegex: '(\\.|/)(test)\\.(jsx?|tsx?)$',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
   setupFiles: ['jest-canvas-mock', './public/test/jest-setup.ts'],

scripts/docs/generate-transformations.test.ts

@@ -0,0 +1,57 @@
+import { getMarkdownContent, getJavaScriptContent, readMeContent } from './generate-transformations.ts';
+
+describe('makefile script tests', () => {
+  it('should execute without error and match the content written to index.md', () => {
+    // Normalize and compare.
+    expect(contentDoesMatch(getJavaScriptContent(), getMarkdownContent())).toBe(true);
+  });
+
+  it('should be able to tell if the content DOES NOT match', () => {
+    const wrongContent = getJavaScriptContent().concat('additional content to mismatch');
+    // Normalize and compare.
+    expect(contentDoesMatch(wrongContent, getMarkdownContent())).toBe(false);
+
+    // If this test fails, refer to `./docs/README.md` "Content guidelines" for more information
+    // about editing and building the Transformations docs.
+  });
+});
+
+export function contentDoesMatch(jsContent: string, mdContent: string): Boolean {
+  return normalizeContent(jsContent) === normalizeContent(mdContent);
+}
+
+/* 
+  Normalize content by removing all whitespace (spaces, tabs, newlines, carriage returns, 
+  form feeds, and vertical tabs) and special characters.
+
+  NOTE: There are numerous unpredictable formatting oddities when transforming JavaScript to Markdown;
+  almost all of them are irrelevant to the actual content of the file, which is why we strip them out here.
+
+  For example:
+
+  In JavaScript, the following string table
+
+  | A | B | C |
+  | - | - | - |
+  | 1 | 3 | 5 |
+  | 2 | 4 | 6 |
+  | 3 | 5 | 7 |
+  | 4 | 6 | 8 |
+  | 5 | 7 | 9 |
+
+  parses to Markdown as
+
+  | A   | B   | C   |
+  | --- | --- | --- | <--------- notice the extra hyphens
+  | 1   | 3   | 5   | <--------- notice the extra spaces
+  | 2   | 4   | 6   |
+  | 3   | 5   | 7   |
+  | 4   | 6   | 8   |
+  | 5   | 7   | 9   |
+
+  This is one of many arbitrary formatting anomalies that we can ignore by normalizing the 
+  content before comparing the JavaScript template literals and the final Markdown.
+*/
+function normalizeContent(content: string): string {
+  return content.replace(/\s+|[`~!@#$%^&*()_|+\-=?;:'",.<>\{\}\[\]\\\/]/g, '').trim();
+}

scripts/docs/generate-transformations.ts

@@ -1,13 +1,15 @@
+import { writeFileSync, readFileSync, read } from 'fs';
+import { resolve } from 'path';
+
 import {
   transformationDocsContent,
   TransformationDocsContentType,
   ImageRenderType,
 } from '../../public/app/features/transformers/docs/content';
 
-const template = `---
-comments: |
-  This Markdown file is auto-generated. DO NOT EDIT THIS FILE DIRECTLY.
+const WRITE_PATH = 'docs/sources/panels-visualizations/query-transform-data/transform-data/index.md';
 
+export const readMeContent = `
   To update this Markdown, navigate to the following Typescript files and edit them based on what you need to update:
 
   scripts/docs/generate-transformations.ts - Includes all content not specific to a transformation.
@@ -24,6 +26,12 @@ comments: |
   Browse to http://localhost:3003/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/
 
   Refer to ./docs/README.md "Content guidelines" for more information about editing and building these docs.
+`;
+
+export const templateMetaContent = `---
+comments: |
+  This Markdown file is auto-generated. DO NOT EDIT THIS FILE DIRECTLY.
+${readMeContent}
 
 aliases:
   - ../../panels/reference-transformation-functions/
@@ -47,9 +55,9 @@ labels:
 title: Transform data
 description: Use transformations to rename fields, join series data, apply mathematical operations, and more
 weight: 100
----
+---`;
 
-# Transform data
+const templateIntroContent = `# Transform data
 
 Transformations are a powerful way to manipulate data returned by a query before the system applies a visualization. Using transformations, you can:
 
@@ -126,13 +134,15 @@ We recommend that you remove transformations that you don't need. When you delet
 1. Click the trash icon next to the transformation you want to delete.
 
 {{< figure src="/static/img/docs/transformations/screenshot-example-remove-transformation.png" class="docs-image--no-shadow" max-width= "1100px" alt="A transformation row with the remove transformation icon highlighted" >}}
+`;
 
+export const completeTemplate = `${templateMetaContent}
+
+${templateIntroContent}
 ## Transformation functions
 
 You can perform the following transformations on your data.
-
 ${buildTransformationDocsContent(transformationDocsContent)}
-
 {{% docs/reference %}}
 [Table panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
 [Table panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
@@ -169,9 +179,8 @@ function buildTransformationDocsContent(transformationDocsContent: Transformatio
   const content = transformationsList
     .map((transformationName) => {
       return `
-  ### ${transformationDocsContent[transformationName].name}
-  ${transformationDocsContent[transformationName].getHelperDocs(ImageRenderType.ShortcodeFigure)}
-  `;
+### ${transformationDocsContent[transformationName].name}
+${transformationDocsContent[transformationName].getHelperDocs(ImageRenderType.ShortcodeFigure)}`;
     })
     // Remove the superfluous commas.
     .join('');
@@ -179,9 +188,20 @@ function buildTransformationDocsContent(transformationDocsContent: Transformatio
   return content;
 }
 
-/*
-  `process.stdout.write(template + '\n')` was not functioning as expected.
-  Neither the tsc nor ts-node compiler could identify the node `process` object.
-  Fortunately, `console.log` also writes to the standard output.
-*/
-console.log(template);
+export function buildMarkdownContent(): void {
+  // Build the path to the Markdown file.
+  const indexPath = resolve(__dirname, '../../' + WRITE_PATH);
+
+  // Write content to the Markdown file.
+  writeFileSync(indexPath, completeTemplate, 'utf-8');
+}
+
+export function getMarkdownContent(): string {
+  const rootDir = resolve(__dirname, '../../');
+  const pathToMarkdown = resolve(rootDir, WRITE_PATH);
+  return readFileSync(pathToMarkdown, 'utf-8');
+}
+
+export function getJavaScriptContent(): string {
+  return completeTemplate;
+}