@cyberismo/data-handler 0.0.8 → 0.0.10

package/src/macros/include/index.ts

@@ -0,0 +1,143 @@
+/**
+  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 { evaluateMacros, 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 { MAX_LEVEL_OFFSET } from '../../utils/constants.js';
+
+export interface IncludeMacroOptions {
+  cardKey: string;
+  levelOffset?: string;
+  title?: 'include' | 'exclude' | 'only';
+  pageTitles?: 'normal' | 'discrete';
+}
+
+export default class IncludeMacro extends BaseMacro {
+  constructor(tasksQueue: TaskQueue) {
+    super(macroMetadata, tasksQueue);
+  }
+
+  handleValidate = (input: unknown) => {
+    this.validate(input);
+  };
+
+  handleStatic = async (
+    context: MacroGenerationContext,
+    input: unknown,
+  ): Promise<string> => {
+    const options = this.validate(input);
+    if (!options.title) {
+      options.title = 'include';
+    }
+    if (!options.pageTitles) {
+      options.pageTitles = 'normal';
+    }
+    const card = await context.project.cardDetailsById(options.cardKey, {
+      content: true,
+      metadata: true,
+    });
+    if (!card) {
+      throw new Error(`Card key ${options.cardKey} not found`);
+    }
+    const newContext = {
+      ...context,
+      cardKey: options.cardKey,
+    };
+
+    const anchor = this.generateAnchor(options);
+    const title = this.generateTitle(options, card.metadata?.title);
+    const cardContent = await this.generateCardContent(
+      options,
+      card.content,
+      newContext,
+    );
+    const content = `\n\n${anchor}${title}${cardContent}`;
+
+    let levelOffset = 0;
+    if (options.levelOffset) {
+      levelOffset = parseInt(options.levelOffset, 10);
+      if (isNaN(levelOffset)) {
+        throw new Error(`Invalid level offset: ${options.levelOffset}`);
+      }
+      levelOffset = Math.min(
+        Math.max(levelOffset, -MAX_LEVEL_OFFSET),
+        MAX_LEVEL_OFFSET,
+      );
+    }
+
+    const adjustedContent = this.adjustTitles(
+      content,
+      levelOffset,
+      options.pageTitles === 'discrete',
+    );
+    return adjustedContent;
+  };
+
+  private validate(input: unknown): IncludeMacroOptions {
+    return validateMacroContent<IncludeMacroOptions>(this.metadata, input);
+  }
+
+  private generateAnchor(options: IncludeMacroOptions): string {
+    return options.title !== 'exclude' && options.pageTitles === 'normal'
+      ? `[[${options.cardKey}]]\n`
+      : '';
+  }
+
+  private generateTitle(
+    options: IncludeMacroOptions,
+    cardTitle?: string,
+  ): string {
+    if (options.title === 'only' || options.title === 'include') {
+      return `= ${cardTitle}\n\n`;
+    }
+    return '';
+  }
+
+  private async generateCardContent(
+    options: IncludeMacroOptions,
+    cardContent: string | undefined,
+    context: MacroGenerationContext,
+  ): Promise<string> {
+    if (options.title !== 'only') {
+      return await evaluateMacros(cardContent ?? '', context, true);
+    }
+    return '';
+  }
+
+  // Adjust asciidoc titles to match the level offset
+  private adjustTitles(
+    content: string,
+    levelOffset: number,
+    discrete: boolean,
+  ) {
+    const lines = content.split('\n');
+    const adjustedLines = lines.map((line) => {
+      const match = line.match(/^(\s*)([=#]+)(.*?)\s*$/);
+      if (match) {
+        const currentLevel = match[2].length;
+        const newLevel = Math.min(
+          Math.max(1, currentLevel + levelOffset),
+          MAX_LEVEL_OFFSET + 1,
+        );
+        const equals = '='.repeat(newLevel);
+        return `${discrete ? '[discrete]\n' : ''}${match[1]}${equals} ${match[3].trim()}`;
+      }
+      return line;
+    });
+    return adjustedLines.join('\n');
+  }
+}

package/src/macros/include/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: 'include',
+  tagName: 'include',
+  schema: 'includeMacroSchema',
+};
+
+export default macroMetadata;

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, MacroError } from '../exceptions/index.js';
 import type { AdmonitionType } from '../interfaces/adoc.js';
-import type { Validator } from 'jsonschema';
 import type {
   MacroGenerationContext,
   MacroMetadata,
@@ -28,10 +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
@@ -44,7 +126,7 @@ export interface SimpleMacroConstructor {
  * Constructor for report macros
  */
 export interface ReportMacroConstructor {
-  new (tasks: TaskQueue, calculate: Calculate): BaseMacro;
+  new (tasks: TaskQueue): BaseMacro;
 }
 
 /**
@@ -57,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`);
@@ -80,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'}`;
@@ -99,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;
 }
 /**
@@ -155,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();
 
@@ -194,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, '}');
 }
 
 /**
@@ -278,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`;
 }
 
 /**
@@ -360,15 +397,30 @@ export function createCodeBlock(content: string) {
  * @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,50 @@
+/**
+  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,
+    );
+  };
+
+  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,11 +12,9 @@
 */
 
 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';
@@ -25,15 +23,12 @@ 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) => {
@@ -41,10 +36,6 @@ class ReportMacro extends BaseMacro {
   };
 
   handleStatic = async (context: MacroGenerationContext, data: unknown) => {
-    return this.handleInject(context, data);
-  };
-
-  handleInject = async (context: MacroGenerationContext, data: unknown) => {
     const options = this.validate(data);
     const resource = new ReportResource(
       context.project,
@@ -61,13 +52,14 @@ class ReportMacro extends BaseMacro {
     }
     try {
       return await generateReportContent({
-        calculate: this.calculate,
+        calculate: context.project.calculationEngine,
         contentTemplate: report.contentTemplate,
         queryTemplate: report.queryTemplate,
         options: {
           cardKey: context.cardKey,
           ...options,
         },
+        context: context.context,
       });
     } catch (error) {
       if (error instanceof ClingoError) {