@cyberismo/data-handler 0.0.13 → 0.0.15

package/src/macros/createCards/index.ts

@@ -12,23 +12,12 @@
 
 import { createHtmlPlaceholder, validateMacroContent } from '../index.js';
 
+import type { CreateCardsOptions } from './types.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';
 
-export interface CreateCardsOptions {
-  buttonLabel: string;
-  template: string;
-  cardKey?: string;
-  link?: {
-    linkType: string;
-    direction: string;
-    cardKey: string;
-  };
-  [key: string]: string | undefined | { [key: string]: string | undefined };
-}
-
 class CreateCardsMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);

package/src/macros/createCards/types.ts

@@ -0,0 +1,46 @@
+/**
+  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/>.
+*/
+
+export interface CreateCardsOptions {
+  /**
+   * Label of the button
+   */
+  buttonLabel: string;
+  /**
+   * Template to create cards from
+   */
+  template: string;
+  /**
+   * Allows forcing card creation under a certain card
+   */
+  cardKey?: string;
+
+  /**
+   * Allows creating a link at the same time
+   */
+  link?: {
+    /**
+     * Type of the link to create
+     */
+    linkType: string;
+    /**
+     * Direction of the link to create
+     */
+    direction: string;
+    /**
+     * Card key of target card of the link
+     */
+    cardKey: string;
+  };
+}

package/src/macros/graph/index.ts

@@ -12,6 +12,7 @@
 */
 
 import BaseMacro from '../base-macro.js';
+import type { GraphOptions } from './types.js';
 import { createImage, validateMacroContent } from '../index.js';
 import Handlebars from 'handlebars';
 import type { MacroGenerationContext } from '../../interfaces/macros.js';
@@ -25,12 +26,7 @@ import { ClingoError } from '@cyberismo/node-clingo';
 import { resourceFilePath } from '../../utils/resource-utils.js';
 import { resourceName } from '../../utils/resource-utils.js';
 
-export interface GraphOptions {
-  model: string;
-  view: string;
-}
-
-class ReportMacro extends BaseMacro {
+class GraphMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);
   }
@@ -129,4 +125,4 @@ class ReportMacro extends BaseMacro {
   }
 }
 
-export default ReportMacro;
+export default GraphMacro;

package/src/macros/graph/types.ts

@@ -0,0 +1,24 @@
+/**
+  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/>.
+*/
+
+export interface GraphOptions {
+  /**
+   * Reference to the model that defines graph
+   */
+  model: string;
+  /**
+   * Reference to the view that defines the graph
+   */
+  view: string;
+}

package/src/macros/image/index.ts

@@ -11,39 +11,64 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import mime from 'mime-types';
 
+import BaseMacro from '../base-macro.js';
+import macroMetadata from './metadata.js';
 import { validateMacroContent } from '../index.js';
 
+import type { ImageMacroOptions } from './types.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';
 
-/**
- * Options for the image macro.
- * @param fileName - Name of the file to include.
- * @param cardKey - Key of the card to include the file from.
- * @param alt - Alternative text for the image.
- * @param title - Title of the image.
- */
-export interface ImageMacroOptions {
-  fileName: string;
-  cardKey?: string;
-  alt?: string;
-  title?: string;
-}
-
 /**
  * Macro for including images in the content
  */
 export default class ImageMacro extends BaseMacro {
+  /**
+   * Constructs ImageMacro instance.
+   * @param tasksQueue Tasks queue
+   */
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);
   }
 
+  // Gets card attachment.
+  private attachment(
+    context: MacroGenerationContext,
+    cardKey: string,
+    filename: string,
+  ) {
+    const card = context.project.findCard(cardKey);
+    const attachment =
+      card.attachments?.find((a) => a.fileName === filename) ?? undefined;
+    if (!attachment) {
+      throw new Error(
+        `Attachment file '${filename}' not found in card '${cardKey}'`,
+      );
+    }
+    return attachment;
+  }
+
+  private buildImageAttributes(options: ImageMacroOptions): string {
+    const attributes: string[] = [];
+
+    if (options.alt !== undefined) {
+      attributes.push(`alt="${options.alt}"`);
+    }
+
+    if (options.title !== undefined) {
+      attributes.push(`title="${options.title}"`);
+    }
+
+    return attributes.join(',');
+  }
+
+  private validate(input: unknown): ImageMacroOptions {
+    return validateMacroContent<ImageMacroOptions>(this.metadata, input);
+  }
+
   handleValidate = (_: MacroGenerationContext, input: unknown) => {
     this.validate(input);
   };
@@ -55,45 +80,27 @@ export default class ImageMacro extends BaseMacro {
     const options = this.validate(input);
     const cardKey = options.cardKey || context.cardKey;
 
-    // Get the attachment folder path
-    const attachmentFolder =
-      await context.project.cardAttachmentFolder(cardKey);
-
-    // Read the file and convert to base64
-    const attachmentPath = join(attachmentFolder, options.fileName);
-    if (!existsSync(attachmentPath)) {
-      throw new Error(
-        `Attachment file '${options.fileName}' not found in card '${cardKey}'`,
-      );
-    }
+    // Get the attachment
+    const cardAttachment = this.attachment(context, cardKey, options.fileName);
 
+    // Convert to base64
+    const attachmentPath = join(cardAttachment?.path, cardAttachment?.fileName);
     const fileBuffer = readFileSync(attachmentPath);
     const base64Data = fileBuffer.toString('base64');
 
-    // Get mime type
-    const mimeType = mime.lookup(attachmentPath) || 'application/octet-stream';
-
     // Build image attributes
     const attributes = this.buildImageAttributes(options);
 
     // Return as data URI for static mode (for export/PDF generation)
-    return `image::data:${mimeType};base64,${base64Data}[${attributes}]`;
+    return `image::data:${cardAttachment.mimeType};base64,${base64Data}[${attributes}]`;
   };
 
   handleInject = async (context: MacroGenerationContext, input: unknown) => {
     const options = this.validate(input);
     const cardKey = options.cardKey || context.cardKey;
 
-    // Verify that the card and attachment folder exist
-    const attachmentFolder =
-      await context.project.cardAttachmentFolder(cardKey);
-
-    const attachmentPath = join(attachmentFolder, options.fileName);
-    if (!existsSync(attachmentPath)) {
-      throw new Error(
-        `Attachment file '${options.fileName}' not found in card '${cardKey}'`,
-      );
-    }
+    // Just verify that the attachment exists.
+    this.attachment(context, cardKey, options.fileName);
 
     // Build image attributes
     const attributes = this.buildImageAttributes(options);
@@ -101,22 +108,4 @@ export default class ImageMacro extends BaseMacro {
     // In inject mode, always use the API path for consistency
     return `image::/api/cards/${cardKey}/a/${options.fileName}[${attributes}]`;
   };
-
-  private buildImageAttributes(options: ImageMacroOptions): string {
-    const attributes: string[] = [];
-
-    if (options.alt !== undefined) {
-      attributes.push(`alt="${options.alt}"`);
-    }
-
-    if (options.title !== undefined) {
-      attributes.push(`title="${options.title}"`);
-    }
-
-    return attributes.join(',');
-  }
-
-  private validate(input: unknown): ImageMacroOptions {
-    return validateMacroContent<ImageMacroOptions>(this.metadata, input);
-  }
 }

package/src/macros/image/types.ts

@@ -0,0 +1,39 @@
+/**
+  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/>.
+*/
+
+/**
+ * Options for the image macro.
+ * @param fileName - Name of the file to include.
+ * @param cardKey - Key of the card to include the file from.
+ * @param alt - Alternative text for the image.
+ * @param title - Title of the image.
+ */
+export interface ImageMacroOptions {
+  /**
+   * Filename of the image
+   */
+  fileName: string;
+  /**
+   * By default, image is assumed to be under the current card. You can override this behaviour
+   */
+  cardKey?: string;
+  /**
+   * Alt text
+   */
+  alt?: string;
+  /**
+   * Title for the image
+   */
+  title?: string;
+}

package/src/macros/include/index.ts

@@ -13,19 +13,13 @@
 
 import { evaluateMacros, validateMacroContent } from '../index.js';
 
+import type { IncludeMacroOptions } from './types.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);
@@ -46,18 +40,11 @@ export default class IncludeMacro extends BaseMacro {
     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 card = this.getCard(options.cardKey, context);
     const anchor = this.generateAnchor(options);
     const title = this.generateTitle(options, card.metadata?.title);
     const cardContent = await this.generateCardContent(
@@ -118,6 +105,10 @@ export default class IncludeMacro extends BaseMacro {
     return '';
   }
 
+  private getCard(cardKey: string, context: MacroGenerationContext) {
+    return context.project.findCard(cardKey);
+  }
+
   // Adjust asciidoc titles to match the level offset
   private adjustTitles(
     content: string,

package/src/macros/include/types.ts

@@ -0,0 +1,32 @@
+/**
+  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/>.
+*/
+
+export interface IncludeMacroOptions {
+  /**
+   * Card key of the card being included
+   */
+  cardKey: string;
+  /**
+   * A positive number wil increase the level of headings and a negative alue will the level of headings in the included content
+   */
+  levelOffset?: string;
+  /**
+   * Determines behaviour with the title that is in card metadata
+   * include --> includes the title
+   * exclude --> excludes the title
+   * only --> includes title but does not import content
+   */
+  title?: 'include' | 'exclude' | 'only';
+  pageTitles?: 'normal' | 'discrete';
+}

package/src/macros/percentage/index.ts

@@ -15,17 +15,11 @@ import { createImage, validateMacroContent } from '../index.js';
 
 import type { MacroGenerationContext } from '../../interfaces/macros.js';
 import macroMetadata from './metadata.js';
+import type { PercentageOptions } from './types.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);

package/src/macros/percentage/types.ts

@@ -0,0 +1,32 @@
+/**
+  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/>.
+*/
+
+export interface PercentageOptions {
+  /**
+   * Title of percentage macro
+   */
+  title: string;
+  /**
+   * Percentage value
+   */
+  value: number;
+  /**
+   * Legend text below the macro
+   */
+  legend: string;
+  /**
+   * Color of the bar the represents the percentage
+   */
+  colour?: 'blue' | 'green' | 'yellow' | 'red' | 'orange' | 'purple';
+}

package/src/macros/report/index.ts

@@ -22,10 +22,7 @@ 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 {
-  name: string;
-}
+import type { ReportOptions } from './types.js';
 
 class ReportMacro extends BaseMacro {
   constructor(tasks: TaskQueue) {

package/src/macros/report/types.ts

@@ -0,0 +1,20 @@
+/**
+  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/>.
+*/
+
+export interface ReportOptions {
+  /**
+   * Name of the report
+   */
+  name: string;
+}

package/src/macros/scoreCard/index.ts

@@ -19,13 +19,7 @@ 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 {
-  value: number;
-  legend?: string;
-  title?: string;
-  unit?: string;
-}
+import type { ScoreCardOptions } from './types.js';
 
 class ScoreCardMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {

package/src/macros/scoreCard/types.ts

@@ -0,0 +1,32 @@
+/**
+  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/>.
+*/
+
+export interface ScoreCardOptions {
+  /**
+   * Value shown in score card
+   */
+  value: number;
+  /**
+   * Optional legend text
+   */
+  legend?: string;
+  /**
+   * Option title text
+   */
+  title?: string;
+  /**
+   * Option unit that is next to the value
+   */
+  unit?: string;
+}

package/src/macros/types.ts

@@ -0,0 +1,48 @@
+/**
+  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 { CreateCardsOptions } from './createCards/types.js';
+import { GraphOptions } from './graph/types.js';
+import { ImageMacroOptions } from './image/types.js';
+import { IncludeMacroOptions } from './include/types.js';
+import { PercentageOptions } from './percentage/types.js';
+import { ReportOptions } from './report/types.js';
+import { ScoreCardOptions } from './scoreCard/types.js';
+import { VegaMacroInput } from './vega/types.js';
+import { VegaLiteMacroInput } from './vegalite/types.js';
+import { XrefMacroOptions } from './xref/types.js';
+
+export type AnyMacroOption =
+  | CreateCardsOptions
+  | GraphOptions
+  | ImageMacroOptions
+  | IncludeMacroOptions
+  | PercentageOptions
+  | ReportOptions
+  | ScoreCardOptions
+  | VegaMacroInput
+  | VegaLiteMacroInput
+  | XrefMacroOptions;
+
+export {
+  CreateCardsOptions,
+  GraphOptions,
+  ImageMacroOptions,
+  IncludeMacroOptions,
+  PercentageOptions,
+  ReportOptions,
+  ScoreCardOptions,
+  VegaMacroInput,
+  VegaLiteMacroInput,
+  XrefMacroOptions,
+};

package/src/macros/vega/index.ts

@@ -21,10 +21,7 @@ import {
   validateMacroContent,
 } from '../index.js';
 import * as vega from 'vega';
-
-export interface VegaMacroInput {
-  spec: vega.Spec;
-}
+import type { VegaMacroInput } from './types.js';
 
 class VegaMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {

package/src/macros/vega/types.ts

@@ -0,0 +1,21 @@
+/**
+  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 { Spec } from 'vega';
+
+export interface VegaMacroInput {
+  /**
+   * Defines spec for vega
+   */
+  spec: Spec;
+}

package/src/macros/vegalite/index.ts

@@ -16,10 +16,7 @@ import macroMetadata from './metadata.js';
 import type TaskQueue from '../task-queue.js';
 import * as vegaLite from 'vega-lite';
 import { createMacro, validateMacroContent } from '../index.js';
-
-export interface VegaLiteMacroInput {
-  spec: vegaLite.TopLevelSpec;
-}
+import type { VegaLiteMacroInput } from './types.js';
 
 class VegaLiteMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {

package/src/macros/vegalite/types.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 { TopLevelSpec } from 'vega-lite';
+
+export interface VegaLiteMacroInput {
+  /**
+   * Defines spec for vega-lite
+   */
+  spec: TopLevelSpec;
+}