@cyberismo/data-handler 0.0.8 → 0.0.10

package/src/containers/project.ts

@@ -13,19 +13,18 @@
 */
 
 // node
-import { type Dirent } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { readdir } from 'node:fs/promises';
 
 import { CardContainer } from './card-container.js'; // base class
 
+import { CalculationEngine } from './project/calculation-engine.js';
 import {
   type Card,
   type CardAttachment,
   CardLocation,
   type CardListContainer,
   type CardMetadata,
-  CardNameRegEx,
   type FetchCardDetails,
   type MetadataContent,
   type ModuleContent,
@@ -36,7 +35,6 @@ import {
   type Resource,
   type ResourceFolderType,
 } from '../interfaces/project-interfaces.js';
-import { findParentPath } from '../utils/card-utils.js';
 import { getFilesSync, pathExists } from '../utils/file-utils.js';
 import { generateRandomString } from '../utils/random.js';
 import { isTemplateCard } from '../utils/card-utils.js';
@@ -74,6 +72,7 @@ export { ResourcesFrom };
  * Represents project folder.
  */
 export class Project extends CardContainer {
+  public calculationEngine: CalculationEngine;
   private resources: ResourceCollector;
   private projectPaths: ProjectPaths;
   private settings: ProjectConfiguration;
@@ -90,6 +89,8 @@ export class Project extends CardContainer {
   ) {
     super(path, '');
 
+    this.calculationEngine = new CalculationEngine(this);
+
     this.settings = new ProjectConfiguration(
       join(path, '.cards', 'local', Project.projectConfigFileName),
     );
@@ -183,7 +184,7 @@ export class Project extends CardContainer {
    * @returns array of all calculation files in the project.
    */
   public async calculations(
-    from: ResourcesFrom = ResourcesFrom.localOnly,
+    from: ResourcesFrom = ResourcesFrom.all,
   ): Promise<Resource[]> {
     return this.resources.resources('calculations', from);
   }
@@ -477,6 +478,30 @@ export class Project extends CardContainer {
     return this.resources.resources('graphViews', from);
   }
 
+  /**
+   * When card changes.
+   * @param changedCard Card that was changed.
+   */
+  public async handleCardChanged(changedCard: Card) {
+    return this.calculationEngine.handleCardChanged(changedCard);
+  }
+
+  /**
+   * When cards are removed.
+   * @param deletedCard Card that is to be removed.
+   */
+  public async handleDeleteCard(deletedCard: Card) {
+    return this.calculationEngine.handleDeleteCard(deletedCard);
+  }
+
+  /**
+   * When new cards are added.
+   * @param cards Added cards.
+   */
+  public async handleNewCards(cards: Card[]) {
+    return this.calculationEngine.handleNewCards(cards);
+  }
+
   /**
    * Checks if a given card is part of this project.
    * @param cardKey card to check.
@@ -986,68 +1011,7 @@ export class Project extends CardContainer {
    * @returns an array of all project cards in the project.
    */
   public async showProjectCards(): Promise<Card[]> {
-    const cards: Card[] = [];
-    const cardPathMap = new Map<string, Card>();
-    const entries = await readdir(this.paths.cardRootFolder, {
-      withFileTypes: true,
-      recursive: true,
-    });
-
-    // Checks if Dirent folder is a card folder
-    function cardFolder(
-      entry: Dirent,
-      cardPathMap: Map<string, Card>,
-    ): Card | undefined {
-      const fullPath = join(entry.parentPath, entry.name);
-      if (!cardPathMap.has(fullPath)) {
-        const newCard: Card = {
-          key: entry.name,
-          path: fullPath,
-          children: [],
-          attachments: [],
-        };
-        cardPathMap.set(fullPath, newCard);
-        return newCard;
-      }
-    }
-
-    // Process card directories first
-    entries
-      .filter((entry) => entry.isDirectory() && CardNameRegEx.test(entry.name))
-      .forEach((entry) => {
-        const card = cardFolder(entry, cardPathMap);
-        if (card) cards.push(card);
-      });
-
-    // Process metadata files in parallel
-    await Promise.all(
-      entries
-        .filter(
-          (entry) => entry.isFile() && entry.name === Project.cardMetadataFile,
-        )
-        .map(async (entry) => {
-          const parentCard = cardPathMap.get(entry.parentPath);
-          if (!parentCard) return;
-          parentCard.metadata = (await readJsonFile(
-            join(entry.parentPath, entry.name),
-          )) as CardMetadata;
-        }),
-    );
-
-    // Finally, build the card hierarchy
-    Array.from(cardPathMap.entries()).map(([cardPath, card]) => {
-      const parentPath = findParentPath(cardPath);
-      if (!parentPath) return;
-      const parentCard = cardPathMap.get(parentPath);
-      if (!parentCard) return;
-
-      parentCard.children.push(card);
-      const index = cards.indexOf(card);
-      if (index > -1) {
-        cards.splice(index, 1);
-      }
-    });
-    return cards;
+    return this.showCards(this.paths.cardRootFolder);
   }
 
   /**

package/src/containers/template.ts

@@ -178,6 +178,14 @@ export class Template extends CardContainer {
       await Promise.all(
         card.attachments.map(async (attachment) => {
           const attachmentUniqueName = `${card.key}-${attachment.fileName}`;
+          content = content?.replace(
+            new RegExp(
+              `(\\{\\{#image\\}\\}[^}]*)"fileName": "${attachment.fileName}"([^}]*\\{\\{\\/image\\}\\})`,
+              'g',
+            ),
+            `$1"fileName": "${attachmentUniqueName}"$2`,
+          );
+          // keep fallback
           content = content?.replace(
             new RegExp(`image::${attachment.fileName}`, 'g'),
             `image::${attachmentUniqueName}`,
@@ -575,4 +583,12 @@ export class Template extends CardContainer {
   public templateFolder(): string {
     return this.templatePath;
   }
+
+  /**
+   * Show cards of a template with hierarchy structure.
+   * @returns an array of all template cards with proper parent-child relationships.
+   */
+  public async showTemplateCards(): Promise<Card[]> {
+    return this.showCards(this.templateCardsPath);
+  }
 }

package/src/index.ts

@@ -17,19 +17,30 @@ import {
   CommandManager,
   ExportFormats,
 } from './command-handler.js';
-import type { Credentials } from './interfaces/project-interfaces.js';
+import { Validate } from './commands/validate.js';
+export * from './interfaces/project-interfaces.js';
 import { requestStatus } from './interfaces/request-status-interfaces.js';
 import { UpdateOperations } from './resources/resource-object.js';
 import { evaluateMacros } from './macros/index.js';
+import {
+  isResourceFolderType,
+  resourceName,
+  resourceNameToString,
+} from './utils/resource-utils.js';
+import { moduleNameFromCardKey } from './utils/card-utils.js';
 
 export {
   CardsOptions,
   Cmd,
   CommandManager,
   Commands,
-  Credentials,
   ExportFormats,
+  isResourceFolderType,
+  moduleNameFromCardKey,
   requestStatus,
+  resourceName,
+  resourceNameToString,
   UpdateOperations,
+  Validate,
   evaluateMacros,
 };

package/src/interfaces/macros.ts

@@ -13,13 +13,16 @@
 import type { macroMetadata } from '../macros/common.js';
 import type { Project } from '../containers/project.js';
 import type { MacroError } from '../exceptions/index.js';
+import type { Context } from './project-interfaces.js';
 
-type Mode = 'validate' | 'static' | 'inject';
+export type Mode = 'validate' | 'static' | 'inject' | 'staticSite';
 
 export interface MacroGenerationContext {
+  context: Context;
   project: Project;
   mode: Mode;
   cardKey: string;
+  maxTries?: number;
 }
 
 export interface MacroMetadata {

package/src/interfaces/project-interfaces.ts

@@ -62,6 +62,14 @@ export interface CardMetadata extends PredefinedCardMetadata {
   [key: string]: MetadataContent;
 }
 
+export const validContexts = ['localApp', 'exportedSite', 'exportedDocument'];
+
+export type Context = 'localApp' | 'exportedSite' | 'exportedDocument';
+
+export const isContext = (context: string): context is Context => {
+  return validContexts.includes(context);
+};
+
 // Content in project (apart from cards) is either .schema files or cardsConfig.json.
 type ContentType = DotSchemaContent | ProjectSettings;
 
@@ -97,6 +105,25 @@ export interface ProjectFetchCardDetails extends FetchCardDetails {
   location?: CardLocation;
 }
 
+/**
+ * Options for exporting to pdf.
+ * @param name - Name of the exported document.
+ * @param title - Title of the exported document.
+ * @param date - Date of the exported document.
+ * @param cardKey - Key of the card to be exported.
+ * @param recursive - Whether to export recursively ie. export all cards below the given card.
+ * @param revremark - Revision remark of the exported document.
+ */
+export interface ExportPdfOptions {
+  name: string;
+  title: string;
+  date?: Date;
+  cardKey?: string;
+  recursive?: boolean;
+  revremark?: string;
+  version?: string;
+}
+
 export type FileContentType = 'adoc' | 'html';
 
 // Metadata content type.

package/src/interfaces/resource-interfaces.ts

@@ -19,8 +19,10 @@ import type { Schema } from 'jsonschema';
  * in a correct place in folder structure.
  */
 
-// Calculation does not have own metadata.
-export type CalculationMetadata = ResourceBaseMetadata;
+// Calculation metadata.
+export interface CalculationMetadata extends ResourceBaseMetadata {
+  calculation: string;
+}
 
 // Card type content.
 export interface CardType extends ResourceBaseMetadata {
@@ -123,6 +125,7 @@ export interface ResourceBaseMetadata {
 
 // All resources metadata content.
 export type ResourceContent =
+  | CalculationMetadata
   | CardType
   | FieldType
   | GraphModel

package/src/macros/base-macro.ts

@@ -42,10 +42,21 @@ abstract class BaseMacro {
     this.globalId = `${generateRandomString(36, 10)}`;
   }
 
-  protected abstract handleInject(
+  // Default: exportSite uses inject output unless overridden by subclass
+  protected handleStaticSite(
     context: MacroGenerationContext,
     input: unknown,
-  ): Promise<string>;
+  ): Promise<string> {
+    return this.handleInject(context, input);
+  }
+
+  // Default: inject uses static output unless overridden by subclass
+  protected handleInject(
+    context: MacroGenerationContext,
+    input: unknown,
+  ): Promise<string> {
+    return this.handleStatic(context, input);
+  }
 
   protected abstract handleStatic(
     context: MacroGenerationContext,
@@ -181,10 +192,14 @@ abstract class BaseMacro {
 
         // Select the function to execute based on context mode
         const functionToCall =
-          context.mode === 'inject' ? this.handleInject : this.handleStatic;
+          context.mode === 'inject'
+            ? this.handleInject
+            : context.mode === 'staticSite'
+              ? this.handleStaticSite
+              : this.handleStatic;
 
         // Execute the function and handle its result
-        return functionToCall(context, parsed);
+        return functionToCall.call(this, context, parsed);
       })
       .then((result) => {
         // undefined is used to indicate that the macro did not run for some reason

package/src/macros/common.ts

@@ -1,24 +1,37 @@
 /**
-    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/>.
 */
 
 // important that this file imports only the metadata
 import createCards from './createCards/metadata.js';
 import graph from './graph/metadata.js';
+import image from './image/metadata.js';
+import include from './include/metadata.js';
 import report from './report/metadata.js';
 import scoreCard from './scoreCard/metadata.js';
+import xref from './xref/metadata.js';
+import percentage from './percentage/metadata.js';
+import vega from './vega/metadata.js';
+import vegaLite from './vegalite/metadata.js';
 
 export const macroMetadata = {
   createCards,
   graph,
+  image,
+  include,
   report,
   scoreCard,
+  xref,
+  percentage,
+  vega,
+  vegaLite,
 };

package/src/macros/createCards/index.ts

@@ -10,7 +10,6 @@
     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 type { MacroGenerationContext } from '../../interfaces/macros.js';
@@ -18,7 +17,7 @@ import macroMetadata from './metadata.js';
 import BaseMacro from '../base-macro.js';
 import type TaskQueue from '../task-queue.js';
 
-export interface CreateCardsOptions extends MacroOptions {
+export interface CreateCardsOptions {
   buttonLabel: string;
   template: string;
   cardKey?: string;
@@ -49,6 +48,11 @@ class CreateCardsMacro extends BaseMacro {
     return createHtmlPlaceholder(this.metadata, options);
   };
 
+  handleStaticSite = async () => {
+    // export site does not support createCards
+    return '';
+  };
+
   private validate(input: unknown): CreateCardsOptions {
     return validateMacroContent<CreateCardsOptions>(this.metadata, input);
   }

package/src/macros/graph/index.ts

@@ -12,8 +12,6 @@
 */
 
 import BaseMacro from '../base-macro.js';
-import { Calculate } from '../../commands/index.js';
-import type { MacroOptions } from '../index.js';
 import { createImage, validateMacroContent } from '../index.js';
 import Handlebars from 'handlebars';
 import { join } from 'node:path';
@@ -27,7 +25,7 @@ import { validateJson } from '../../utils/validate.js';
 import type TaskQueue from '../task-queue.js';
 import { ClingoError } from '@cyberismo/node-clingo';
 
-export interface GraphOptions extends MacroOptions {
+export interface GraphOptions {
   model: string;
   view: string;
 }
@@ -42,12 +40,6 @@ class ReportMacro extends BaseMacro {
   };
 
   handleStatic = async (context: MacroGenerationContext, input: unknown) => {
-    return this.handleInject(context, input);
-  };
-
-  handleInject = async (context: MacroGenerationContext, input: unknown) => {
-    const calculate = new Calculate(context.project);
-
     const resourceNameToPath = (name: string, fileName: string) => {
       const { identifier, prefix, type } = resourceName(name);
       if (prefix === context.project.projectPrefix) {
@@ -114,7 +106,11 @@ class ReportMacro extends BaseMacro {
     const modelContent = await readFile(modelLocation, { encoding: 'utf-8' });
     let result: string;
     try {
-      result = await calculate.runGraph(modelContent, view);
+      result = await context.project.calculationEngine.runGraph(
+        modelContent,
+        view,
+        context.context,
+      );
     } catch (error) {
       if (error instanceof ClingoError) {
         throw new Error(

package/src/macros/image/index.ts

@@ -0,0 +1,128 @@
+/**
+  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 { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import mime from 'mime-types';
+
+import { 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';
+
+/**
+ * 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 {
+  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);
+    const cardKey = options.cardKey || context.cardKey;
+
+    // Get the attachment folder path
+    const attachmentFolder =
+      await context.project.cardAttachmentFolder(cardKey);
+    if (!attachmentFolder) {
+      throw new Error(`Card '${cardKey}' not found`);
+    }
+
+    // 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}'`,
+      );
+    }
+
+    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}]`;
+  };
+
+  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);
+    if (!attachmentFolder) {
+      throw new Error(`Card '${cardKey}' not found`);
+    }
+
+    const attachmentPath = join(attachmentFolder, options.fileName);
+    if (!existsSync(attachmentPath)) {
+      throw new Error(
+        `Attachment file '${options.fileName}' not found in card '${cardKey}'`,
+      );
+    }
+
+    // Build image attributes
+    const attributes = this.buildImageAttributes(options);
+
+    // 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/metadata.ts

@@ -0,0 +1,25 @@
+/**
+  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';
+
+/**
+ * Metadata for the image macro.
+ */
+const macroMetadata: MacroMetadata = {
+  name: 'image',
+  tagName: 'image',
+  schema: 'imageMacroSchema',
+};
+
+export default macroMetadata;