@cyberismo/data-handler 0.0.10 → 0.0.12

package/src/containers/project.ts

@@ -110,23 +110,25 @@ export class Project extends CardContainer {
       this.resourceWatcher = new ContentWatcher(
         ignoreRenameFileChanges,
         this.paths.resourcesFolder,
-        async (fileName: string) => {
-          let resource;
-          try {
-            resource = pathToResourceName(
-              this,
-              join(this.paths.resourcesFolder, fileName),
-            );
-            if (!resource) {
+        (fileName: string) => {
+          void (async () => {
+            let resource;
+            try {
+              resource = pathToResourceName(
+                this,
+                join(this.paths.resourcesFolder, fileName),
+              );
+              if (!resource) {
+                return;
+              }
+            } catch {
+              // it wasn't a resource that changed, so ignore the change
               return;
             }
-          } catch {
-            // it wasn't a resource that changed, so ignore the change
-            return;
-          }
-          const resourceName = `${resource.prefix}/${resource.type}/${resource.identifier}`;
-          await this.replaceCacheValue(resourceName);
-          this.resources.collectLocalResources();
+            const resourceName = `${resource.prefix}/${resource.type}/${resource.identifier}`;
+            await this.replaceCacheValue(resourceName);
+            this.resources.collectLocalResources();
+          })();
         },
       );
     }
@@ -164,6 +166,7 @@ export class Project extends CardContainer {
   /**
    * Add a given 'resource' to the local resource arrays.
    * @param resource Resource to add.
+   * @param data JSON data for the resource.
    */
   public addResource(resource: Resource, data: JSON) {
     this.resources.add(resource);
@@ -193,6 +196,7 @@ export class Project extends CardContainer {
    * Returns path to card's attachment folder.
    * @param cardKey card key
    * @returns path to card's attachment folder.
+   * @throws if card path cannot be found
    */
   public async cardAttachmentFolder(cardKey: string): Promise<string> {
     // Check if it is a template card.
@@ -202,9 +206,10 @@ export class Project extends CardContainer {
     }
 
     const pathToProjectCard = this.pathToCard(cardKey);
-    return pathToProjectCard
-      ? join(this.paths.cardRootFolder, pathToProjectCard, 'a')
-      : '';
+    if (!pathToProjectCard) {
+      throw new Error(`Card '${cardKey}' not found`);
+    }
+    return join(this.paths.cardRootFolder, pathToProjectCard, 'a');
   }
 
   /**
@@ -252,6 +257,7 @@ export class Project extends CardContainer {
    * Returned parts are: prefix, card key, array of parents and template name. Template name is returned only for template cards.
    * @param cardPath path to a card
    * @returns card path logical parts
+   * @throws when called with wrong path, or wrong card owner
    * todo: if prefix would be parameter; this could be static, or util method
    */
   public cardPathParts(cardPath: string) {
@@ -458,7 +464,7 @@ export class Project extends CardContainer {
 
   /**
    * Returns an array of all the graph models in the project.
-   * @param from  Defines where resources are collected from.
+   * @param from Defines where resources are collected from.
    * @returns array of all the graph models in the project.
    */
   public async graphModels(
@@ -469,7 +475,7 @@ export class Project extends CardContainer {
 
   /**
    * Returns an array of all the graph views in the project.
-   * @param from  Defines where resources are collected from.
+   * @param from Defines where resources are collected from.
    * @returns array of all the graph views in the project.
    */
   public async graphViews(
@@ -513,7 +519,7 @@ export class Project extends CardContainer {
 
   /**
    * Adds a module from project.
-   * @param moduleName Name of the module
+   * @param module Name of the module
    */
   public async importModule(module: ModuleSetting) {
     // Add module as a dependency.
@@ -534,6 +540,7 @@ export class Project extends CardContainer {
    * Returns whether card is a template card or not
    * @param cardKey card to check.
    * @todo: This is only used from 'remove'. Could it use the static checker?
+   * @returns true, if card is template card; false otherwise
    */
   public async isTemplateCard(cardKey: string): Promise<boolean> {
     const templateCards = await this.allTemplateCards();
@@ -554,7 +561,7 @@ export class Project extends CardContainer {
   /**
    * Returns an array of cards in the project, in the templates or both.
    * Cards don't have content and nor metadata.
-   * @param includeCardsFrom Where to return cards from (project, templates, or both)
+   * @param cardsFrom Where to return cards from (project, templates, or both)
    * @returns all cards in the project.
    */
   public async listCards(
@@ -603,7 +610,7 @@ export class Project extends CardContainer {
 
   /**
    * Return cardIDs of the cards in the project or from templates, or both.
-   * @param includeCardsFrom Where to return cards from (project, templates, or both)
+   * @param cardsFrom Where to return cards from (project, templates, or both)
    * @returns Array of cardIDs.
    * @note that cardIDs are not sorted.
    */
@@ -626,41 +633,35 @@ export class Project extends CardContainer {
       cardsFrom === CardLocation.templatesOnly
     ) {
       promises.push(
-        this.templates().then((templates) =>
-          Promise.allSettled(
-            templates.map(
-              (template) =>
-                new TemplateResource(this, resourceName(template.name)),
-            ),
-          )
-            .then((results) =>
-              results
-                .filter(
-                  (
-                    result,
-                  ): result is PromiseFulfilledResult<TemplateResource> =>
-                    result.status === 'fulfilled' && result.value !== null,
-                )
-                .map((result) => result.value),
+        (async () => {
+          const templates = await this.templates();
+          const templateResources = templates.map(
+            (template) =>
+              new TemplateResource(this, resourceName(template.name)),
+          );
+          const templateObjectsResults =
+            await Promise.allSettled(templateResources);
+          const templateObjects = templateObjectsResults
+            .filter(
+              (result): result is PromiseFulfilledResult<TemplateResource> =>
+                result.status === 'fulfilled' && result.value !== null,
             )
-            .then((templateObjects) =>
-              Promise.allSettled(
-                templateObjects.map((obj) => obj.templateObject().listCards()),
-              ),
+            .map((result) => result.value);
+
+          const listCardsResults = await Promise.allSettled(
+            templateObjects.map((obj) => obj.templateObject().listCards()),
+          );
+          const templateCardIds = new Set<string>();
+          listCardsResults
+            .filter(
+              (result): result is PromiseFulfilledResult<Card[]> =>
+                result.status === 'fulfilled',
             )
-            .then((results) => {
-              const templateCardIds = new Set<string>();
-              results
-                .filter(
-                  (result): result is PromiseFulfilledResult<Card[]> =>
-                    result.status === 'fulfilled',
-                )
-                .forEach((result) => {
-                  result.value.forEach((card) => templateCardIds.add(card.key));
-                });
-              return templateCardIds;
-            }),
-        ),
+            .forEach((result) => {
+              result.value.forEach((card) => templateCardIds.add(card.key));
+            });
+          return templateCardIds;
+        })(),
       );
     }
     const allCardIdSets = await Promise.all(promises);
@@ -682,6 +683,7 @@ export class Project extends CardContainer {
       return {
         name: moduleConfig.name,
         modules: moduleConfig.modules,
+        hubs: moduleConfig.hubs,
         path: modulePath,
         cardKeyPrefix: moduleConfig.cardKeyPrefix,
         calculations: [
@@ -754,6 +756,7 @@ export class Project extends CardContainer {
   /**
    * Returns a new unique card key with project prefix (e.g. test_x649it4x).
    * Random part of string will be always 8 characters in base-36 (0-9a-z)
+   * @param cardIds map of card ids in use already
    * @returns a new card key string
    * @throws if a unique key could not be created within set number of attempts
    */
@@ -772,12 +775,14 @@ export class Project extends CardContainer {
       return newKey;
     }
 
-    throw 'Could not generate unique card key';
+    throw new Error('Could not generate unique card key');
   }
 
   /**
    * Returns an array of new unique card keys with project prefix (e.g. test_x649it4x).
    * Random part of string will be always 8 characters in base-36 (0-9a-z)
+   * @param keysToCreate How many new cards are to be created.
+   * @param cardIds map of card ids in use already
    * @returns an array of new card key strings
    * @throws if a unique key could not be created within set number of attempts
    */
@@ -809,7 +814,7 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Getter. Returns a class that handles the project's paths.
+   * Returns a class that handles the project's paths.
    */
   public get paths(): ProjectPaths {
     return this.projectPaths;
@@ -828,14 +833,14 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Getter. Returns project name.
+   * Returns project name.
    */
   public get projectName(): string {
     return this.settings.name;
   }
 
   /**
-   * Getter. Returns project prefix.
+   * Returns project prefix.
    */
   public get projectPrefix(): string {
     return this.settings.cardKeyPrefix;
@@ -869,7 +874,7 @@ export class Project extends CardContainer {
       const configurationPrefixes = await Promise.all(configurationPromises);
       prefixes.push(...configurationPrefixes);
     } catch {
-      // do nothing if readdir throws
+      // do nothing if readdir throws // TODO: Log it
     }
 
     return prefixes;
@@ -937,6 +942,9 @@ export class Project extends CardContainer {
     return data;
   }
 
+  /**
+   * Returns resource cache.
+   */
   public get resourceCache(): Map<string, JSON> {
     return this.createdResources;
   }
@@ -1000,6 +1008,7 @@ export class Project extends CardContainer {
       name: this.containerName,
       path: this.basePath,
       prefix: this.projectPrefix,
+      hubs: this.configuration.hubs,
       modules: (await this.modules()).map((item) => item.name),
       numberOfCards: (await this.listCards(CardLocation.projectOnly))[0].cards
         .length,
@@ -1131,6 +1140,7 @@ export class Project extends CardContainer {
   /**
    * Validates that card's data is valid.
    * @param card Card to validate.
+   * @returns validation errors, if any
    */
   public async validateCard(card: Card): Promise<string> {
     const invalidCustomData = await this.validator.validateCustomFields(

package/src/containers/template.ts

@@ -439,7 +439,7 @@ export class Template extends CardContainer {
   public async cardAttachmentFolder(cardKey: string): Promise<string> {
     const pathToCard = await this.cardFolder(cardKey);
     if (!pathToCard) {
-      return '';
+      throw new Error(`Template card '${cardKey}' not found`);
     }
     return join(pathToCard, 'a');
   }

package/src/interfaces/project-interfaces.ts

@@ -164,6 +164,7 @@ export interface ProjectMetadata {
   path: string;
   prefix: string;
   modules: string[];
+  hubs: HubSetting[];
   numberOfCards: number;
 }
 
@@ -172,6 +173,20 @@ export interface ProjectSettings {
   cardKeyPrefix: string;
   name: string;
   modules: ModuleSetting[];
+  hubs: HubSetting[];
+}
+
+// Hub configuration
+export interface HubSetting {
+  location: string;
+  description?: string;
+  displayName?: string;
+}
+
+// Module configuration for a hub.
+export interface ModuleSettingFromHub extends ModuleSetting {
+  documentationLocation: string;
+  displayName: string;
 }
 
 // Module configuration.
@@ -195,6 +210,7 @@ export type RemovableResourceTypes =
   | 'fieldType'
   | 'graphModel'
   | 'graphView'
+  | 'hub'
   | 'link'
   | 'linkType'
   | 'module'
@@ -229,6 +245,8 @@ export type ResourceTypes =
   | 'attachments'
   | 'calculation'
   | 'cards'
+  | 'hubs'
+  | 'importableModules'
   | 'label'
   | 'labels'
   | 'links'

package/src/macros/base-macro.ts

@@ -63,7 +63,10 @@ abstract class BaseMacro {
     input: unknown,
   ): Promise<string>;
 
-  protected abstract handleValidate(input: unknown): void;
+  protected abstract handleValidate(
+    context: MacroGenerationContext,
+    input: unknown,
+  ): void;
 
   public get metadata() {
     return this.macroMetadata;
@@ -127,7 +130,7 @@ abstract class BaseMacro {
 
     if (context.mode === 'validate') {
       try {
-        this.handleValidate(JSON.parse(input));
+        this.handleValidate(context, JSON.parse(input));
       } catch (error) {
         if (error instanceof Error) {
           const errorMessage = `From card '${context.cardKey}' a macro validation error:\n\n${error.message}.\n\nCard content:\n ${input}`;

package/src/macros/createCards/index.ts

@@ -34,7 +34,7 @@ class CreateCardsMacro extends BaseMacro {
     super(macroMetadata, tasksQueue);
   }
 
-  handleValidate = (input: unknown) => {
+  handleValidate = (_: MacroGenerationContext, input: unknown) => {
     this.validate(input);
   };
 

package/src/macros/graph/index.ts

@@ -14,16 +14,16 @@
 import BaseMacro from '../base-macro.js';
 import { createImage, validateMacroContent } from '../index.js';
 import Handlebars from 'handlebars';
-import { join } from 'node:path';
 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 { resourceName } from '../../utils/resource-utils.js';
+import { readFileSync } from 'node:fs';
 import type { Schema } from 'jsonschema';
-import { validateJson } from '../../utils/validate.js';
 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;
@@ -35,55 +35,23 @@ class ReportMacro extends BaseMacro {
     super(macroMetadata, tasksQueue);
   }
 
-  handleValidate = (input: unknown) => {
-    this.parseOptions(input);
+  handleValidate = (context: MacroGenerationContext, input: unknown) => {
+    this.parseOptions(input, context);
   };
 
   handleStatic = async (context: MacroGenerationContext, input: unknown) => {
-    const resourceNameToPath = (name: string, fileName: string) => {
-      const { identifier, prefix, type } = resourceName(name);
-      if (prefix === context.project.projectPrefix) {
-        return join(
-          context.project.paths.resourcesFolder,
-          type,
-          identifier,
-          fileName,
-        );
-      }
-      return join(
-        context.project.paths.modulesFolder,
-        prefix,
-        type,
-        identifier,
-        fileName,
-      );
-    };
-
-    const options = this.parseOptions(input);
-
-    let schema: Schema | null = null;
-    try {
-      schema = JSON.parse(
-        await readFile(
-          resourceNameToPath(options.view, 'parameterSchema.json'),
-          { encoding: 'utf-8' },
-        ),
-      );
-    } catch (err) {
-      this.logger.trace(
-        err,
-        'Graph schema not found or failed to read, skipping validation',
-      );
-    }
-
-    if (schema) {
-      validateJson(options, {
-        schema,
-      });
-    }
-
-    const modelLocation = resourceNameToPath(options.model, 'model.lp');
-    const viewLocation = resourceNameToPath(options.view, 'view.lp.hbs');
+    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',
+    );
 
     if (!pathExists(modelLocation)) {
       throw new Error(`Graph: Model ${options.model} does not exist`);
@@ -128,8 +96,36 @@ class ReportMacro extends BaseMacro {
     return createImage(result);
   };
 
-  private parseOptions(input: unknown): GraphOptions {
-    return validateMacroContent<GraphOptions>(this.metadata, input);
+  private parseOptions(
+    input: unknown,
+    context: MacroGenerationContext,
+  ): 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',
+      );
+    }
+
+    if (schema) {
+      validateMacroContent(this.metadata, input, schema);
+    }
+
+    return options;
   }
 }
 

package/src/macros/image/index.ts

@@ -44,7 +44,7 @@ export default class ImageMacro extends BaseMacro {
     super(macroMetadata, tasksQueue);
   }
 
-  handleValidate = (input: unknown) => {
+  handleValidate = (_: MacroGenerationContext, input: unknown) => {
     this.validate(input);
   };
 
@@ -58,9 +58,6 @@ export default class ImageMacro extends BaseMacro {
     // 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);
@@ -90,9 +87,6 @@ export default class ImageMacro extends BaseMacro {
     // 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)) {

package/src/macros/include/index.ts

@@ -31,7 +31,7 @@ export default class IncludeMacro extends BaseMacro {
     super(macroMetadata, tasksQueue);
   }
 
-  handleValidate = (input: unknown) => {
+  handleValidate = (_: MacroGenerationContext, input: unknown) => {
     this.validate(input);
   };
 

package/src/macros/index.ts

@@ -153,6 +153,7 @@ export const macros: {
  * Validates the content inside a macro
  * @param macro - The macro to validate the content of
  * @param data - The data to validate
+ * @param schema - Schema to use in validation
  * @returns The validated data
  */
 export function validateMacroContent<T>(
@@ -180,7 +181,10 @@ export function validateMacroContent<T>(
 
 /**
  * Registers the macros with Handlebars
- * @param {Mode} mode - The mode to register the macros in
+ * @param instance - Handlebar instance
+ * @param context - The context for macro generation
+ * @param tasks - Tasks to register
+ * @returns macro instances
  */
 export function registerMacros(
   instance: typeof Handlebars,
@@ -201,7 +205,8 @@ export function registerMacros(
 }
 /**
  * Calculate amount of handlebars templates inside a string
- * @param input
+ * @param input - String to calculate templates from
+ * @returns number of macros
  */
 export function macroCount(input: string): number {
   const regex = /{{#[\w\s-]+?}}/g;
@@ -224,11 +229,11 @@ export function registerEmptyMacros(instance: typeof Handlebars) {
 }
 
 /**
- * Handle the macros in the content
+ * Handle the macros in the content.
  * @param content - The content to handle the macros in
  * @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)
+ * @returns macro result
  */
 export async function evaluateMacros(
   content: string,
@@ -240,7 +245,7 @@ export async function evaluateMacros(
   registerMacros(handlebars, context, tasks);
   let result = content;
   while ((context.maxTries ?? 10) > 0) {
-    tasks.reset();
+    await tasks.reset();
     try {
       const compiled = handlebars.compile(preprocessRawBlocks(result), {
         strict: true,
@@ -313,6 +318,7 @@ export function applyMacroResults(
  * Handles errors that come when handling macros
  * @param error - The error that was thrown
  * @param macro - The macro that caused the error
+ * @param context - General context for the macro evaluation process
  * @returns The error message that is valid adoc
  */
 export function handleMacroError(
@@ -350,9 +356,14 @@ export function handleMacroError(
 }
 
 // This is used to generate unique keys for macros
-// There might be a better way to do this
+// TODO: There might be a better way to do this
 let macroCounter = 0;
 
+/**
+ * Converts object to base64
+ * @param obj Object to convert
+ * @returns base64 conversion (as a Buffer)
+ */
 function objectToBase64(obj: unknown): string {
   return Buffer.from(JSON.stringify(obj), 'utf-8').toString('base64');
 }
@@ -393,8 +404,9 @@ export function createCodeBlock(content: string) {
 }
 
 /**
- * Helper function for including base64 encoded images for now
+ * Helper function for including base64 encoded images
  * @param image base64 encoded image
+ * @param controls Add controls
  * @returns valid asciidoc with the image
  */
 export function createImage(image: string, controls: boolean = true) {

package/src/macros/percentage/index.ts

@@ -30,7 +30,7 @@ class PercentageMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);
   }
-  handleValidate = (data: string) => {
+  handleValidate = (_: MacroGenerationContext, data: string) => {
     this.validate(data);
   };
 

package/src/macros/report/index.ts

@@ -31,7 +31,7 @@ class ReportMacro extends BaseMacro {
   constructor(tasks: TaskQueue) {
     super(macroMetadata, tasks);
   }
-  handleValidate = (input: unknown) => {
+  handleValidate = (_: MacroGenerationContext, input: unknown) => {
     this.validate(input);
   };
 

package/src/macros/scoreCard/index.ts

@@ -31,7 +31,7 @@ class ScoreCardMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);
   }
-  handleValidate = (data: string) => {
+  handleValidate = (_: MacroGenerationContext, data: string) => {
     this.validate(data);
   };
 

package/src/macros/vega/index.ts

@@ -31,7 +31,7 @@ class VegaMacro extends BaseMacro {
     super(macroMetadata, tasksQueue);
   }
 
-  handleValidate = (input: unknown) => {
+  handleValidate = (_: MacroGenerationContext, input: unknown) => {
     this.validate(input);
   };
 

package/src/macros/vegalite/index.ts

@@ -26,7 +26,7 @@ class VegaLiteMacro extends BaseMacro {
     super(macroMetadata, tasksQueue);
   }
 
-  handleValidate = (input: unknown) => {
+  handleValidate = (_: MacroGenerationContext, input: unknown) => {
     this.validate(input);
   };