@cyberismo/data-handler 0.0.7 → 0.0.9

package/src/macros/index.ts

@@ -1,26 +1,32 @@
 /**
-    Cyberismo
-    Copyright © Cyberismo Ltd and contributors 2024
-
-    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
-
-    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-
-    You should have received a copy of the GNU Affero General Public
-    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+  details. You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
 import Handlebars from 'handlebars';
 
 import createCards from './createCards/index.js';
 import graph from './graph/index.js';
+import image from './image/index.js';
+import include from './include/index.js';
 import report from './report/index.js';
 import scoreCard from './scoreCard/index.js';
+import xref from './xref/index.js';
+import percentage from './percentage/index.js';
+import vega from './vega/index.js';
+import vegaLite from './vegalite/index.js';
 
 import { validateJson } from '../utils/validate.js';
-import { DHValidationError } from '../exceptions/index.js';
+import { DHValidationError, MacroError } from '../exceptions/index.js';
 import type { AdmonitionType } from '../interfaces/adoc.js';
-import type { Validator } from 'jsonschema';
 import type {
   MacroGenerationContext,
   MacroMetadata,
@@ -28,9 +34,86 @@ import type {
 } from '../interfaces/macros.js';
 import type BaseMacro from './base-macro.js';
 import TaskQueue from './task-queue.js';
-import type { Calculate } from '../commands/index.js';
+import { ClingoError } from '@cyberismo/node-clingo';
+import type { Schema } from 'jsonschema';
 const CURLY_LEFT = '&#123;';
 const CURLY_RIGHT = '&#125;';
+const RAW_BLOCK_OPEN = '{{#raw}}';
+const RAW_BLOCK_CLOSE = '{{/raw}}';
+
+/**
+ * Pre-processes the content to handle {{#raw}} blocks by escaping all handlebars syntax inside them
+ * @param content The template content to process
+ * @returns The processed content with raw blocks escaped
+ * @throws Error if nested raw blocks are found or if a raw block is not properly closed
+ */
+function preprocessRawBlocks(content: string): string {
+  const result: string[] = [];
+  let i = 0;
+
+  // Helper function to check if a target string matches at a given position without creating substrings
+  const matchesAt = (pos: number, target: string): boolean => {
+    if (pos + target.length > content.length) return false;
+    for (let k = 0; k < target.length; k++) {
+      if (content[pos + k] !== target[k]) return false;
+    }
+    return true;
+  };
+
+  // Helper function to get line number at position
+  const getLineNumber = (pos: number): number => {
+    let lineNum = 1;
+    for (let k = 0; k < pos; k++) {
+      if (content[k] === '\n') {
+        lineNum++;
+      }
+    }
+    return lineNum;
+  };
+
+  while (i < content.length) {
+    // Check for {{#raw}}
+    if (matchesAt(i, RAW_BLOCK_OPEN)) {
+      const openingLine = getLineNumber(i);
+      // Find the matching {{/raw}} - no nesting allowed
+      let j = i + RAW_BLOCK_OPEN.length;
+
+      while (j < content.length) {
+        if (matchesAt(j, RAW_BLOCK_OPEN)) {
+          // Found nested raw block - not supported
+          const nestedLine = getLineNumber(j);
+          throw new Error(
+            `Nested ${RAW_BLOCK_OPEN} blocks are not supported. Found nested raw block inside another raw block on line ${nestedLine} (original raw block started on line ${openingLine}).`,
+          );
+        } else if (matchesAt(j, RAW_BLOCK_CLOSE)) {
+          // Found matching closing tag
+          const rawContent = content.slice(i + RAW_BLOCK_OPEN.length, j);
+          const escapedContent = rawContent
+            .replaceAll('{', CURLY_LEFT)
+            .replaceAll('}', CURLY_RIGHT);
+          result.push(escapedContent);
+          i = j + RAW_BLOCK_CLOSE.length;
+          break;
+        } else {
+          j++;
+        }
+      }
+
+      // If we reached the end without finding a closing tag
+      if (j >= content.length) {
+        throw new Error(
+          `Unclosed ${RAW_BLOCK_OPEN} block found on line ${openingLine}. Every ${RAW_BLOCK_OPEN} must have a matching ${RAW_BLOCK_CLOSE}.`,
+        );
+      }
+    } else {
+      // Not a raw block, keep as-is
+      result.push(content[i]);
+      i++;
+    }
+  }
+
+  return result.join('');
+}
 
 /**
  * Constructor for all macros except report macros
@@ -43,7 +126,7 @@ export interface SimpleMacroConstructor {
  * Constructor for report macros
  */
 export interface ReportMacroConstructor {
-  new (tasks: TaskQueue, calculate: Calculate): BaseMacro;
+  new (tasks: TaskQueue): BaseMacro;
 }
 
 /**
@@ -56,21 +139,26 @@ export const macros: {
 } = {
   createCards,
   graph,
+  image,
+  include,
   report,
   scoreCard,
+  xref,
+  percentage,
+  vega,
+  vegaLite,
 };
 
 /**
  * Validates the content inside a macro
  * @param macro - The macro to validate the content of
  * @param data - The data to validate
- * @param validator - The validator to use
  * @returns The validated data
  */
 export function validateMacroContent<T>(
   macro: MacroMetadata,
   data: unknown,
-  validator?: Validator,
+  schema?: Schema,
 ): T {
   if (!macro.schema) {
     throw new Error(`Macro ${macro.name} does not have a schema`);
@@ -79,7 +167,7 @@ export function validateMacroContent<T>(
   try {
     return validateJson<T>(data, {
       schemaId: macro.schema,
-      validator,
+      schema,
     });
   } catch (error) {
     let message = `Error: ${error instanceof Error ? error.message : 'Unknown error'}`;
@@ -98,33 +186,17 @@ export function registerMacros(
   instance: typeof Handlebars,
   context: MacroGenerationContext,
   tasks: TaskQueue,
-  calculate: Calculate,
 ) {
   const macroInstances: BaseMacro[] = [];
   for (const macro of Object.keys(macros) as MacroName[]) {
     const MacroClass = macros[macro];
-    const macroInstance = new MacroClass(tasks, calculate);
+    const macroInstance = new MacroClass(tasks);
     instance.registerHelper(macro, function (this: unknown, options) {
-      if (
-        this != null &&
-        typeof this === 'object' &&
-        '__isRaw' in this &&
-        this.__isRaw
-      ) {
-        // we use escaped chars so that they will not be re-run
-        return `${CURLY_LEFT}${CURLY_LEFT}#${macro}${CURLY_RIGHT}${CURLY_RIGHT}${options.fn(this)}${CURLY_LEFT}${CURLY_LEFT}/${macro}${CURLY_RIGHT}${CURLY_RIGHT}`;
-      }
       return macroInstance.invokeMacro(context, options);
     });
     macroInstances.push(macroInstance);
   }
 
-  instance.registerHelper('raw', function (options) {
-    return options.fn({
-      __isRaw: true,
-    });
-  });
-
   return macroInstances;
 }
 /**
@@ -154,25 +226,26 @@ export function registerEmptyMacros(instance: typeof Handlebars) {
 /**
  * Handle the macros in the content
  * @param content - The content to handle the macros in
- * @param mode - The mode to handle the macros in. Inject mode will generate injectable placeholders for the macros while static mode will generate valid adoc. Validate mode will only validate the macros syntax and throw errors in case of issues.
+ * @param context - The context for macro generation
+ * @param calculate - The calculate function
+ * @param preserveRawBlocks - If true, don't unescape raw blocks at the end (for nested evaluations)
  */
 export async function evaluateMacros(
   content: string,
   context: MacroGenerationContext,
-  calculate: Calculate,
-  maxTries: number = 10,
+  preserveRawBlocks: boolean = false,
 ) {
   const handlebars = Handlebars.create();
   const tasks = new TaskQueue();
-  registerMacros(handlebars, context, tasks, calculate);
+  registerMacros(handlebars, context, tasks);
   let result = content;
-  while (maxTries-- > 0) {
+  while ((context.maxTries ?? 10) > 0) {
     tasks.reset();
-    const compiled = handlebars.compile(result, {
-      strict: true,
-    });
     try {
-      result = compiled({});
+      const compiled = handlebars.compile(preprocessRawBlocks(result), {
+        strict: true,
+      });
+      result = compiled({ cardKey: context.cardKey });
 
       await tasks.waitAll();
 
@@ -193,7 +266,10 @@ export async function evaluateMacros(
       context,
     );
   }
-  return result.replaceAll(CURLY_LEFT, '{').replaceAll(CURLY_RIGHT, '}');
+  // Only unescape raw blocks if we're not preserving them for nested evaluations
+  return preserveRawBlocks
+    ? result
+    : result.replaceAll(CURLY_LEFT, '{').replaceAll(CURLY_RIGHT, '}');
 }
 
 /**
@@ -211,7 +287,14 @@ export function applyMacroResults(
   context: MacroGenerationContext,
 ) {
   for (const item of tasks) {
-    if (item.promiseResult === null) {
+    if (item.error) {
+      input = input.replace(
+        item.placeholder,
+        handleMacroError(item.error, item.macro, context),
+      );
+    } // It should not be possible that promiseResult is null if there never was an error
+    // Unless the function itself returns null / undefined
+    else if (item.promiseResult == null) {
       input = handleMacroError(
         new Error(
           `Tried to access result before it was resolved for ${item.placeholder}`,
@@ -240,7 +323,17 @@ export function handleMacroError(
   let message = `Error: ${error instanceof Error ? error.message : 'Unknown error'}`;
   if (error instanceof DHValidationError) {
     message = `Check json syntax of macro ${macro}: ${error.errors?.map((e) => e.message).join(', ')}`;
+  } else if (error instanceof MacroError) {
+    const { cardKey, macroName, dependency } = error.context;
+    message = `Macro error in card '${cardKey}' in macro '${macroName}':\n\n${error.message}.`;
+
+    if (dependency) {
+      message += `\n\nParameters:\n\n${context.mode === 'validate' ? dependency.parameters : createCodeBlock(dependency.parameters)}.\n\n${dependency.output ? `Output:\n\n${context.mode === 'validate' ? dependency.output : createCodeBlock(dependency.output)}` : ''}`;
+    }
+  } else if (error instanceof ClingoError) {
+    message = `Error running logic program in macro '${macro}':${error.details.errors.join('\n')}`;
   }
+
   if (
     typeof error === 'object' &&
     error != null &&
@@ -260,57 +353,19 @@ export function handleMacroError(
 // There might be a better way to do this
 let macroCounter = 0;
 
-type Value = string | number | boolean | undefined;
-
-/**
- * Macro options can be a flat object or a nested object
- * The nested object will be flattened into dot notation attributes
- */
-export type MacroOptions = {
-  [key: string]: Value | MacroOptions;
-};
+function objectToBase64(obj: unknown): string {
+  return Buffer.from(JSON.stringify(obj), 'utf-8').toString('base64');
+}
 /**
- * Creates an injectable placeholder for a macro
- * @param macro - The macro to create the placeholder for
- * @param options - Options will be passed to the html element as attributes
+ * Creates a placeholder for a macro
+ * Options are encoded as base64
+ * @param macro - The macro to create a placeholder for
+ * @param options - The options for the macro
+ * @returns The placeholder for the macro
  */
-export function createHtmlPlaceholder(
-  macro: MacroMetadata,
-  options: MacroOptions,
-) {
-  // Flatten nested objects into dot notation attributes
-  const flattenedOptions: Record<string, Value> = {};
-
-  // Helper function to flatten nested objects
-  const flatten = (obj: MacroOptions, prefix = ''): void => {
-    Object.entries(obj).forEach(([key, value]) => {
-      const newKey = prefix ? `${prefix}.${key}` : key;
-
-      if (
-        value !== null &&
-        typeof value === 'object' &&
-        !Array.isArray(value)
-      ) {
-        // Recursively flatten nested objects
-        flatten(value, newKey);
-      } else {
-        // Add leaf values to flattened options
-        flattenedOptions[newKey] = value as Value;
-      }
-    });
-  };
-
-  flatten(options);
-
-  // Convert flattened options to attribute strings
-  const attributeStrings = Object.entries(flattenedOptions)
-    .filter(([, value]) => value !== undefined)
-    .map(([key, value]) => `${key}="${value}"`);
-
-  const optionString = attributeStrings.join(' ');
-
-  // start with a line change to ensure that inline passthrough +++ is on its own line
-  return `\n+++\n<${macro.tagName}${optionString ? ` ${optionString}` : ''} key="macro-${macroCounter++}"></${macro.tagName}>\n+++\n`;
+export function createHtmlPlaceholder(macro: MacroMetadata, options: unknown) {
+  const optionsBase64 = objectToBase64(options);
+  return `\n\n++++\n<${macro.tagName} options="${optionsBase64}" key="macro-${macroCounter++}"></${macro.tagName}>\n++++\n\n`;
 }
 
 /**
@@ -328,20 +383,44 @@ export function createAdmonition(
   return `[${type}]\n.${label}\n====\n${content}\n====\n\n`;
 }
 
+/**
+ * Creates a code block
+ * @param content - The content of the code block
+ * @returns The code block as a string
+ */
+export function createCodeBlock(content: string) {
+  return `\n\n----\n${content}\n----\n\n`;
+}
+
 /**
  * Helper function for including base64 encoded images for now
  * @param image base64 encoded image
  * @returns valid asciidoc with the image
  */
-export function createImage(image: string) {
+export function createImage(image: string, controls: boolean = true) {
   if (process.env.EXPORT_FORMAT) {
     return `image::data:image/svg+xml;base64,${image}[]\n`;
   } else {
-    return `++++
-<div class="cyberismo-svg-wrapper" data-type="cyberismo-svg-wrapper">
-${Buffer.from(image, 'base64').toString('utf-8')}
-</div>
-++++
-`;
+    const svg = Buffer.from(image, 'base64').toString('utf-8');
+    if (controls) {
+      return `++++\n<div class="cyberismo-svg-wrapper" data-type="cyberismo-svg-wrapper">\n${svg}\n</div>\n++++\n`;
+    } else {
+      return `++++\n${svg}\n++++\n`;
+    }
+  }
+}
+
+/**
+ * Creates a Handlebars macro block string with the given macro name and options.
+ *
+ * @param macro - The name of the macro to create (e.g., 'scoreCard', 'include').
+ * @param options - The options object to be stringified and inserted as macro content.
+ * @returns The Handlebars macro block as a string, e.g. {{#macro}}...{{/macro}}
+ */
+export function createMacro(macro: MacroName, options: unknown) {
+  let optionsString = JSON.stringify(options, null, 0);
+  if (optionsString.length > 1) {
+    optionsString = optionsString.slice(1, -1);
   }
+  return `{{#${macro}}}${optionsString}{{/${macro}}}`;
 }

package/src/macros/percentage/index.ts

@@ -0,0 +1,54 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { createImage, validateMacroContent } from '../index.js';
+
+import type { MacroGenerationContext } from '../../interfaces/macros.js';
+import macroMetadata from './metadata.js';
+import BaseMacro from '../base-macro.js';
+import type TaskQueue from '../task-queue.js';
+import { percentage } from '../../svg/index.js';
+
+export interface PercentageOptions {
+  title: string;
+  value: number;
+  legend: string;
+  colour?: 'blue' | 'green' | 'yellow' | 'red' | 'orange' | 'purple';
+}
+
+class PercentageMacro extends BaseMacro {
+  constructor(tasksQueue: TaskQueue) {
+    super(macroMetadata, tasksQueue);
+  }
+  handleValidate = (data: string) => {
+    this.validate(data);
+  };
+
+  handleStatic = async (_: MacroGenerationContext, input: unknown) => {
+    const options = this.validate(input);
+    return createImage(
+      Buffer.from(percentage(options)).toString('base64'),
+      false,
+    );
+  };
+
+  handleInject = async (context: MacroGenerationContext, input: unknown) => {
+    return this.handleStatic(context, input);
+  };
+
+  private validate(input: unknown): PercentageOptions {
+    return validateMacroContent<PercentageOptions>(this.metadata, input);
+  }
+}
+
+export default PercentageMacro;

package/src/macros/percentage/metadata.ts

@@ -0,0 +1,22 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import type { MacroMetadata } from '../../interfaces/macros.js';
+
+const macroMetadata: MacroMetadata = {
+  name: 'percentage',
+  tagName: 'percentage',
+  schema: 'percentageMacroSchema',
+};
+
+export default macroMetadata;

package/src/macros/report/index.ts

@@ -12,27 +12,23 @@
 */
 
 import { validateMacroContent } from '../index.js';
-import type { MacroOptions } from '../index.js';
 
 import type { MacroGenerationContext } from '../../interfaces/macros.js';
 import macroMetadata from './metadata.js';
-import type { Calculate } from '../../commands/index.js';
 import BaseMacro from '../base-macro.js';
 import { validateJson } from '../../utils/validate.js';
 import type TaskQueue from '../task-queue.js';
 import { ReportResource } from '../../resources/report-resource.js';
 import { resourceName } from '../../utils/resource-utils.js';
 import { generateReportContent } from '../../utils/report.js';
+import { ClingoError } from '@cyberismo/node-clingo';
 
-export interface ReportOptions extends MacroOptions {
+export interface ReportOptions {
   name: string;
 }
 
 class ReportMacro extends BaseMacro {
-  constructor(
-    tasks: TaskQueue,
-    private readonly calculate: Calculate,
-  ) {
+  constructor(tasks: TaskQueue) {
     super(macroMetadata, tasks);
   }
   handleValidate = (input: unknown) => {
@@ -58,16 +54,25 @@ class ReportMacro extends BaseMacro {
         schema: report.schema,
       });
     }
-
-    return generateReportContent({
-      calculate: this.calculate,
-      contentTemplate: report.contentTemplate,
-      queryTemplate: report.queryTemplate,
-      options: {
-        cardKey: context.cardKey,
-        ...options,
-      },
-    });
+    try {
+      return await generateReportContent({
+        calculate: context.project.calculationEngine,
+        contentTemplate: report.contentTemplate,
+        queryTemplate: report.queryTemplate,
+        options: {
+          cardKey: context.cardKey,
+          ...options,
+        },
+        context: context.context,
+      });
+    } catch (error) {
+      if (error instanceof ClingoError) {
+        throw new Error(
+          `Error running logic program in report '${options.name}':${error.details.errors.join('\n')}`,
+        );
+      }
+      throw error;
+    }
   };
 
   private validate(data: unknown): ReportOptions {

package/src/macros/scoreCard/index.ts

@@ -1,28 +1,30 @@
 /**
-    Cyberismo
-    Copyright © Cyberismo Ltd and contributors 2024
-
-    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
-
-    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-
-    You should have received a copy of the GNU Affero General Public
-    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import type { MacroOptions } from '../index.js';
-import { createHtmlPlaceholder, validateMacroContent } from '../index.js';
+import { createImage, validateMacroContent } from '../index.js';
 
 import type { MacroGenerationContext } from '../../interfaces/macros.js';
 import macroMetadata from './metadata.js';
 import BaseMacro from '../base-macro.js';
 import type TaskQueue from '../task-queue.js';
+import { scoreCard } from '../../svg/index.js';
 
-export interface ScoreCardOptions extends MacroOptions {
-  title?: string;
+export interface ScoreCardOptions {
   value: number;
-  unit?: string;
   legend?: string;
+  title?: string;
+  unit?: string;
 }
 
 class ScoreCardMacro extends BaseMacro {
@@ -33,23 +35,21 @@ class ScoreCardMacro extends BaseMacro {
     this.validate(data);
   };
 
-  handleStatic = async (context: MacroGenerationContext, input: unknown) => {
+  handleStatic = async (_: MacroGenerationContext, input: unknown) => {
     const options = this.validate(input);
-    return this.createAsciidocElement(options);
+    return createImage(
+      Buffer.from(scoreCard(options)).toString('base64'),
+      false,
+    );
   };
 
-  handleInject = async (_: MacroGenerationContext, input: unknown) => {
-    const options = this.validate(input);
-    return createHtmlPlaceholder(this.metadata, options);
+  handleInject = async (context: MacroGenerationContext, input: unknown) => {
+    return this.handleStatic(context, input);
   };
 
   private validate(input: unknown): ScoreCardOptions {
     return validateMacroContent<ScoreCardOptions>(this.metadata, input);
   }
-
-  private createAsciidocElement(options: ScoreCardOptions) {
-    return `\n----\n${options.title}: ${options.value} ${options.unit ?? ''} ${options.legend ?? ''}\n----\n`;
-  }
 }
 
 export default ScoreCardMacro;