@cyberismo/data-handler 0.0.7 → 0.0.9

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.
@@ -660,31 +685,58 @@ export class Project extends CardContainer {
         path: modulePath,
         cardKeyPrefix: moduleConfig.cardKeyPrefix,
         calculations: [
-          ...(await this.resources.collectResourcesFromModules('calculations')),
+          ...(await this.resources.collectResourcesFromModules(
+            'calculations',
+            moduleName,
+          )),
         ],
         cardTypes: [
-          ...(await this.resources.collectResourcesFromModules('cardTypes')),
+          ...(await this.resources.collectResourcesFromModules(
+            'cardTypes',
+            moduleName,
+          )),
         ],
         fieldTypes: [
-          ...(await this.resources.collectResourcesFromModules('fieldTypes')),
+          ...(await this.resources.collectResourcesFromModules(
+            'fieldTypes',
+            moduleName,
+          )),
         ],
         graphModels: [
-          ...(await this.resources.collectResourcesFromModules('graphModels')),
+          ...(await this.resources.collectResourcesFromModules(
+            'graphModels',
+            moduleName,
+          )),
         ],
         graphViews: [
-          ...(await this.resources.collectResourcesFromModules('graphViews')),
+          ...(await this.resources.collectResourcesFromModules(
+            'graphViews',
+            moduleName,
+          )),
         ],
         linkTypes: [
-          ...(await this.resources.collectResourcesFromModules('linkTypes')),
+          ...(await this.resources.collectResourcesFromModules(
+            'linkTypes',
+            moduleName,
+          )),
         ],
         reports: [
-          ...(await this.resources.collectResourcesFromModules('reports')),
+          ...(await this.resources.collectResourcesFromModules(
+            'reports',
+            moduleName,
+          )),
         ],
         templates: [
-          ...(await this.resources.collectResourcesFromModules('templates')),
+          ...(await this.resources.collectResourcesFromModules(
+            'templates',
+            moduleName,
+          )),
         ],
         workflows: [
-          ...(await this.resources.collectResourcesFromModules('workflows')),
+          ...(await this.resources.collectResourcesFromModules(
+            'workflows',
+            moduleName,
+          )),
         ],
       };
     }
@@ -823,15 +875,6 @@ export class Project extends CardContainer {
     return prefixes;
   }
 
-  /**
-   * Removes a module from project.
-   * @param moduleName Name of the module
-   */
-  public async removeModule(moduleName: string) {
-    await this.configuration.removeModule(moduleName);
-    await this.collectModuleResources();
-  }
-
   /**
    * Array of reports in the project.
    * @param from Defines where resources are collected from.
@@ -968,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/exceptions/index.ts

@@ -27,3 +27,39 @@ export class SchemaNotFound extends Error {
     this.name = 'SchemaNotFound';
   }
 }
+/**
+ * Stores the context of a macro error that originated from another macro
+ */
+export interface MacroDependency {
+  macroName: string;
+  parameters: string;
+  output?: string;
+}
+/**
+ * Thrown when a macro fails to execute.
+ */
+export class MacroError extends Error {
+  public context: {
+    cardKey: string;
+    macroName: string;
+    parameters: string;
+    dependency?: MacroDependency;
+  };
+
+  constructor(
+    message: string,
+    cardKey: string,
+    macroName: string,
+    parameters: string,
+    dependency?: MacroDependency,
+  ) {
+    super(message);
+    this.name = 'MacroError';
+    this.context = {
+      cardKey,
+      macroName,
+      parameters,
+      dependency,
+    };
+  }
+}

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

@@ -12,13 +12,17 @@
 
 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';
 
 export interface MacroGenerationContext {
+  context: Context;
   project: Project;
   mode: Mode;
   cardKey: string;
+  maxTries?: number;
 }
 
 export interface MacroMetadata {
@@ -44,6 +48,8 @@ export interface MacroTaskState {
   placeholder: string;
   promiseResult: string | null;
   macro: string;
+  parameters: string;
+  error: MacroError | null;
 }
 
 // Handlebars options is not documented

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

@@ -123,6 +123,7 @@ export interface ResourceBaseMetadata {
 
 // All resources metadata content.
 export type ResourceContent =
+  | CalculationMetadata
   | CardType
   | FieldType
   | GraphModel

package/src/macros/base-macro.ts

@@ -17,13 +17,23 @@ import type {
   MacroTaskState,
 } from '../interfaces/macros.js';
 import { generateRandomString } from '../utils/random.js';
-import { handleMacroError } from './index.js';
+import { MacroError } from '../exceptions/index.js';
 import type TaskQueue from './task-queue.js';
+import { ClingoError } from '@cyberismo/node-clingo';
+import { getChildLogger } from '../utils/log-utils.js';
 
 abstract class BaseMacro {
   private globalId: string;
   private localCounter: number = 0;
 
+  // Macros share the same logger
+  protected get logger() {
+    return getChildLogger({
+      module: 'macro',
+      macro: this.macroMetadata.name,
+    });
+  }
+
   constructor(
     protected macroMetadata: MacroMetadata,
     private readonly tasks: TaskQueue,
@@ -64,7 +74,7 @@ abstract class BaseMacro {
       if (task) {
         dependencies.push(task);
       } else {
-        console.warn(
+        this.logger.warn(
           `Dependency not found for placeholder: ${placeholder} (globalId: ${globalId}, localId: ${localId})`,
         );
       }
@@ -81,6 +91,16 @@ abstract class BaseMacro {
     };
   }
 
+  private findTask(globalId: string, localId: number) {
+    const task = this.tasks.find(globalId, localId);
+    if (!task) {
+      this.logger.warn(
+        `Task not found for global id ${globalId}, local id ${localId}.`,
+      );
+    }
+    return task;
+  }
+
   /**
    * Function responsible for starting the promise and storing it along with its localId.
    */
@@ -111,20 +131,53 @@ abstract class BaseMacro {
     const dependencies = this.findDependencies(rawInput);
 
     // Create a promise to resolve dependencies, execute the macro, and handle the results
-    const promise = Promise.all(dependencies.map((dep) => dep.promise))
+    const promise = Promise.allSettled(dependencies.map((dep) => dep.promise))
       .then(() => {
         for (const dependency of dependencies) {
+          if (dependency.error) {
+            const task = this.findTask(this.globalId, localId);
+            if (task) {
+              // There could be a better way, but multi-nested macros are rare
+              task.error = new MacroError(
+                dependency.error.message,
+                context.cardKey,
+                this.metadata.name,
+                dependency.error.context.parameters,
+                {
+                  macroName: dependency.macro,
+                  parameters: dependency.parameters,
+                },
+              );
+            }
+            return;
+          }
           input = input.replace(
             dependency.placeholder,
             dependency.promiseResult || '',
           );
+          // parse json after each dep, so we know the exact macro which produced the error
+          try {
+            JSON.parse(input);
+          } catch {
+            const task = this.findTask(this.globalId, localId);
+            if (task) {
+              task.error = new MacroError(
+                'Invalid JSON produced by macro dependency',
+                context.cardKey,
+                this.metadata.name,
+                input,
+                {
+                  macroName: dependency.macro,
+                  parameters: dependency.parameters,
+                  output: input,
+                },
+              );
+            }
+            return;
+          }
         }
-        let parsed;
-        try {
-          parsed = JSON.parse(input);
-        } catch {
-          return 'Invalid JSON';
-        }
+        // This will never throw in practice, thus no need to catch
+        const parsed = JSON.parse(input);
 
         // Select the function to execute based on context mode
         const functionToCall =
@@ -134,28 +187,37 @@ abstract class BaseMacro {
         return functionToCall(context, parsed);
       })
       .then((result) => {
-        const task = this.tasks.find(this.globalId, localId);
+        // undefined is used to indicate that the macro did not run for some reason
+        if (result === undefined) {
+          return;
+        }
+        const task = this.findTask(this.globalId, localId);
         if (task) {
           task.promiseResult = result;
-        } else {
-          console.error(
-            `Task not found after execution: macro ${this.metadata.name}, local id ${localId}.`,
-          );
         }
       })
       .catch((err) => {
-        const task = this.tasks.find(this.globalId, localId);
+        if (!(err instanceof Error)) {
+          this.logger.error(err, 'Unknown error');
+          err = new Error('Unknown error');
+        }
+        const message =
+          err instanceof ClingoError
+            ? err.details.errors.join('\n')
+            : err.message;
+        const error =
+          err instanceof MacroError
+            ? err
+            : new MacroError(
+                message,
+                context.cardKey,
+                this.metadata.name,
+                input,
+              );
+
+        const task = this.findTask(this.globalId, localId);
         if (task) {
-          task.promiseResult = handleMacroError(
-            err,
-            this.metadata.name,
-            context,
-          );
-        } else {
-          console.error(
-            `Error handling task for macro ${this.metadata.name}, local id ${localId}:`,
-            err,
-          );
+          task.error = error;
         }
       });
 
@@ -167,6 +229,8 @@ abstract class BaseMacro {
       placeholder,
       promiseResult: null,
       macro: this.macroMetadata.name,
+      parameters: rawInput,
+      error: null,
     });
     // Return the placeholder
     return placeholder;

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;