@cyberismo/data-handler 0.0.14 → 0.0.16

package/src/interfaces/resource-interfaces.ts

@@ -17,6 +17,7 @@ import type {
   GraphViewContent,
   ReportContent,
 } from './folder-content-interfaces.js';
+import type { ResourceType } from './project-interfaces.js';
 
 /**
  * Each resource represents a file (or a folder in some cases) with metadata stored
@@ -46,12 +47,6 @@ export interface CardType extends ResourceBaseMetadata {
   optionallyVisibleFields: string[];
 }
 
-// Base content update key interface
-export interface ContentUpdateKey {
-  key: 'content';
-  subKey: string; // Resource-specific types should narrow this
-}
-
 // Custom field
 // todo: merge with FieldType.
 export interface CustomField {
@@ -95,11 +90,6 @@ export interface GraphModel extends GraphModelMetadata {
   content: GraphModelContent;
 }
 export type GraphModelContentPropertyName = 'model';
-export interface GraphModelContentUpdateKey {
-  key: 'content';
-  subKey: GraphModelContentPropertyName;
-}
-export type GraphModelUpdateKey = string | GraphModelContentUpdateKey;
 
 // Graph view content.
 export interface GraphViewMetadata extends ResourceBaseMetadata {
@@ -109,11 +99,6 @@ export type GraphViewContentPropertyName = 'viewTemplate';
 export interface GraphView extends GraphViewMetadata {
   content: GraphViewContent;
 }
-export interface GraphViewContentUpdateKey {
-  key: 'content';
-  subKey: GraphViewContentPropertyName;
-}
-export type GraphViewUpdateKey = string | GraphViewContentUpdateKey;
 
 // Link content.
 export interface Link {
@@ -132,7 +117,7 @@ export interface LinkType extends ResourceBaseMetadata {
 }
 
 // Report resource.
-export interface Report extends ResourceBaseMetadata {
+export interface Report extends ReportMetadata {
   content: ReportContent;
 }
 
@@ -141,11 +126,6 @@ export type ReportContentPropertyName =
   | 'contentTemplate'
   | 'queryTemplate'
   | 'schema';
-export interface ReportContentUpdateKey {
-  key: 'content';
-  subKey: ReportContentPropertyName;
-}
-export type ReportUpdateKey = string | ReportContentUpdateKey;
 
 // Metadata for report
 export interface ReportMetadata extends ResourceBaseMetadata {
@@ -161,17 +141,31 @@ export interface ResourceBaseMetadata {
 }
 
 // All resources metadata content.
-export type ResourceContent =
-  | CalculationMetadata
+export type AnyResourceContent =
+  | Calculation
   | CardType
   | FieldType
   | GraphModel
   | GraphView
   | LinkType
-  | ReportMetadata
+  | Report
   | TemplateMetadata
   | Workflow;
 
+export type ResourceContent<T extends ResourceType> = ResourceContentMap[T];
+
+export type ResourceContentMap = {
+  calculations: Calculation;
+  cardTypes: CardType;
+  fieldTypes: FieldType;
+  graphModels: GraphModel;
+  graphViews: GraphView;
+  linkTypes: LinkType;
+  reports: Report;
+  templates: TemplateMetadata;
+  workflows: Workflow;
+};
+
 // Template configuration details.
 export interface TemplateConfiguration extends TemplateMetadata {
   path: string;
@@ -182,9 +176,18 @@ export interface TemplateConfiguration extends TemplateMetadata {
 export interface TemplateMetadata extends ResourceBaseMetadata {
   category?: string;
 }
+type ContentUpdateKey = { key: 'content'; subKey: string };
+type PropertyUpdateKey<K extends string = string> = {
+  key: Exclude<K, 'content'>;
+};
+
+export type UpdateKey<K extends string = string> =
+  | ContentUpdateKey
+  | PropertyUpdateKey<K>;
 
-// Generic update key
-export type UpdateKey = string | ContentUpdateKey;
+export function isContentKey(key: UpdateKey): key is ContentUpdateKey {
+  return key.key === 'content';
+}
 
 // Workflow's json file content.
 export interface Workflow extends ResourceBaseMetadata {

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

@@ -14,23 +14,14 @@
 import BaseMacro from '../base-macro.js';
 import { createImage, validateMacroContent } from '../index.js';
 import Handlebars from 'handlebars';
-import type { MacroGenerationContext } from '../../interfaces/macros.js';
 import macroMetadata from './metadata.js';
-import { pathExists } from '../../utils/file-utils.js';
-import { readFile } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
-import type { Schema } from 'jsonschema';
-import type TaskQueue from '../task-queue.js';
 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;
-}
+import type { GraphOptions } from './types.js';
+import type { MacroGenerationContext } from '../../interfaces/macros.js';
+import type TaskQueue from '../task-queue.js';
 
-class ReportMacro extends BaseMacro {
+class GraphMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);
   }
@@ -42,40 +33,35 @@ class ReportMacro extends BaseMacro {
   handleStatic = async (context: MacroGenerationContext, input: unknown) => {
     const options = this.parseOptions(input, context);
 
-    const modelLocation = resourceFilePath(
-      context.project,
-      resourceName(options.model),
-      'model.lp',
-    );
-    const viewLocation = resourceFilePath(
-      context.project,
-      resourceName(options.view),
-      'view.lp.hbs',
+    const modelResource = context.project.resources.byType(
+      options.model,
+      'graphModels',
     );
+    const modelContent = modelResource.contentData();
 
-    if (!pathExists(modelLocation)) {
-      throw new Error(`Graph: Model ${options.model} does not exist`);
+    const viewResource = context.project.resources.byType(
+      options.view,
+      'graphViews',
+    );
+    const viewContent = viewResource.contentData();
+    if (!viewContent.viewTemplate) {
+      throw new Error(`Graph: View ${options.view} has no view template`);
     }
 
-    let viewContent = '';
-    try {
-      viewContent = await readFile(viewLocation, { encoding: 'utf-8' });
-    } catch {
-      throw new Error(`Graph: View ${options.view} does not exist`);
-    }
     const handlebarsContext = {
       cardKey: context.cardKey,
       ...options,
     };
 
     const handlebars = Handlebars.create();
-    const view = handlebars.compile(viewContent)(handlebarsContext);
+    const view = handlebars.compile(viewContent.viewTemplate)(
+      handlebarsContext,
+    );
 
-    const modelContent = await readFile(modelLocation, { encoding: 'utf-8' });
     let result: string;
     try {
       result = await context.project.calculationEngine.runGraph(
-        modelContent,
+        modelContent.model,
         view,
         context.context,
       );
@@ -102,24 +88,13 @@ class ReportMacro extends BaseMacro {
   ): GraphOptions {
     const options = validateMacroContent<GraphOptions>(this.metadata, input);
 
-    let schema: Schema | null = null;
-    try {
-      schema = JSON.parse(
-        readFileSync(
-          resourceFilePath(
-            context.project,
-            resourceName(options.view),
-            'parameterSchema.json',
-          ),
-          { encoding: 'utf-8' },
-        ),
-      );
-    } catch (err) {
-      this.logger.trace(
-        err,
-        'Graph schema not found or failed to read, skipping validation',
-      );
-    }
+    // Get schema from view resource content if available
+    const resource = context.project.resources.byType(
+      options.view,
+      'graphViews',
+    );
+    const content = resource.contentData();
+    const schema = content.schema;
 
     if (schema) {
       validateMacroContent(this.metadata, input, schema);
@@ -129,4 +104,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/index.ts

@@ -186,7 +186,7 @@ export function validateMacroContent<T>(
  * @param tasks - Tasks to register
  * @returns macro instances
  */
-export function registerMacros(
+export async function registerMacros(
   instance: typeof Handlebars,
   context: MacroGenerationContext,
   tasks: TaskQueue,
@@ -242,7 +242,7 @@ export async function evaluateMacros(
 ) {
   const handlebars = Handlebars.create();
   const tasks = new TaskQueue();
-  registerMacros(handlebars, context, tasks);
+  await registerMacros(handlebars, context, tasks);
   let result = content;
   while ((context.maxTries ?? 10) > 0) {
     await tasks.reset();

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);