@cyberismo/data-handler 0.0.11 → 0.0.13

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/interfaces/resource-interfaces.ts

@@ -11,7 +11,11 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import type { Schema } from 'jsonschema';
+import type {
+  GraphModelContent,
+  GraphViewContent,
+  ReportContent,
+} from './folder-content-interfaces.js';
 
 /**
  * Each resource represents a file (or a folder in some cases) with metadata stored
@@ -32,6 +36,12 @@ 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 {
@@ -71,19 +81,29 @@ export interface FieldType extends ResourceBaseMetadata {
 export interface GraphModelMetadata extends ResourceBaseMetadata {
   category?: string;
 }
-
 export interface GraphModel extends GraphModelMetadata {
-  calculationFile: string;
+  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 {
   category?: string;
 }
-
+export type GraphViewContentPropertyName = 'viewTemplate';
 export interface GraphView extends GraphViewMetadata {
-  handleBarFile: string;
+  content: GraphViewContent;
 }
+export interface GraphViewContentUpdateKey {
+  key: 'content';
+  subKey: GraphViewContentPropertyName;
+}
+export type GraphViewUpdateKey = string | GraphViewContentUpdateKey;
 
 // Link content.
 export interface Link {
@@ -103,13 +123,20 @@ export interface LinkType extends ResourceBaseMetadata {
 
 // Report resource.
 export interface Report extends ResourceBaseMetadata {
-  name: string;
-  metadata: ReportMetadata;
-  contentTemplate: string;
-  queryTemplate: string;
-  schema?: Schema;
+  content: ReportContent;
 }
 
+// Resource-specific content names
+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 {
   category: string;
@@ -136,10 +163,9 @@ export type ResourceContent =
   | Workflow;
 
 // Template configuration details.
-export interface TemplateConfiguration extends ResourceBaseMetadata {
+export interface TemplateConfiguration extends TemplateMetadata {
   path: string;
   numberOfCards: number;
-  metadata: TemplateMetadata;
 }
 
 // Template configuration content details.
@@ -147,6 +173,9 @@ export interface TemplateMetadata extends ResourceBaseMetadata {
   category?: string;
 }
 
+// Generic update key
+export type UpdateKey = string | ContentUpdateKey;
+
 // Workflow's json file content.
 export interface Workflow extends ResourceBaseMetadata {
   states: WorkflowState[];

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);
   };
 
@@ -45,16 +45,16 @@ class ReportMacro extends BaseMacro {
 
     if (!report) throw new Error(`Report ${options.name} does not exist`);
 
-    if (report.schema) {
+    if (report.content.schema) {
       validateJson(options, {
-        schema: report.schema,
+        schema: report.content.schema,
       });
     }
     try {
       return await generateReportContent({
         calculate: context.project.calculationEngine,
-        contentTemplate: report.contentTemplate,
-        queryTemplate: report.queryTemplate,
+        contentTemplate: report.content.contentTemplate,
+        queryTemplate: report.content.queryTemplate,
         options: {
           cardKey: context.cardKey,
           ...options,

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

package/src/macros/xref/index.ts

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

package/src/project-settings.ts

@@ -13,9 +13,11 @@
 
 import { writeJsonFile as atomicWrite } from 'write-json-file';
 
-import { resolve } from 'path';
+import { resolve } from 'node:path';
+import { URL } from 'node:url';
 
 import type {
+  HubSetting,
   ModuleSetting,
   ProjectSettings,
 } from './interfaces/project-interfaces.js';
@@ -31,6 +33,7 @@ export class ProjectConfiguration implements ProjectSettings {
   name: string;
   cardKeyPrefix: string;
   modules: ModuleSetting[];
+  hubs: HubSetting[];
   private settingPath: string;
 
   constructor(path: string) {
@@ -38,6 +41,7 @@ export class ProjectConfiguration implements ProjectSettings {
     this.settingPath = path;
     this.cardKeyPrefix = '';
     this.modules = [];
+    this.hubs = [];
     this.readSettings();
   }
 
@@ -70,6 +74,7 @@ export class ProjectConfiguration implements ProjectSettings {
       this.cardKeyPrefix = settings.cardKeyPrefix;
       this.name = settings.name;
       this.modules = settings.modules || [];
+      this.hubs = settings.hubs || [];
     } else {
       throw new Error(`Invalid configuration file '${this.settingPath}'`);
     }
@@ -81,9 +86,51 @@ export class ProjectConfiguration implements ProjectSettings {
       cardKeyPrefix: this.cardKeyPrefix,
       name: this.name,
       modules: this.modules,
+      hubs: this.hubs,
     };
   }
 
+  /**
+   * Adds a new hub.
+   * @param hubName URL of the hub to add
+   * @throws if hub is already in the project or URL is invalid
+   */
+  public async addHub(hubName: string) {
+    const trimmedHub = hubName?.trim();
+    if (!trimmedHub) {
+      throw new Error(`Cannot add empty hub to the project`);
+    }
+
+    const exists = this.hubs.find((item) => item.location === trimmedHub);
+    if (exists) {
+      throw new Error(
+        `Hub '${trimmedHub}' already exists as a hub for the project`,
+      );
+    }
+
+    try {
+      const hubUrl = new URL(trimmedHub);
+      if (!['http:', 'https:'].includes(hubUrl.protocol)) {
+        throw new Error(
+          `Invalid URL protocol '${hubUrl.protocol}'. Only HTTP and HTTPS protocols are supported for hubs.`,
+        );
+      }
+      if (!hubUrl.hostname) {
+        throw new Error('Hub URL must have a valid hostname.');
+      }
+    } catch (error) {
+      if (error instanceof TypeError) {
+        throw new Error(
+          `Invalid hub URL '${trimmedHub}'. Please provide a valid HTTP or HTTPS URL.`,
+        );
+      }
+      throw error;
+    }
+
+    this.hubs.push({ location: trimmedHub });
+    return this.save();
+  }
+
   /**
    * Adds new module to imported modules property.
    * @param module Module to add as dependency
@@ -105,6 +152,20 @@ export class ProjectConfiguration implements ProjectSettings {
     return this.save();
   }
 
+  /**
+   * Removes a hub.
+   * @param hubName Name of the hub to remove.
+   * @throws if hub is not part of the project
+   */
+  public async removeHub(hubName: string) {
+    const exists = this.hubs.find((item) => item.location === hubName);
+    if (!exists) {
+      throw new Error(`Hub '${hubName}' not part of the project`);
+    }
+    this.hubs = this.hubs.filter((item) => item.location !== hubName);
+    return this.save();
+  }
+
   /**
    * Removes module from imported modules property.
    * @param moduleName Name of the module to remove.

package/src/resources/card-type-resource.ts

@@ -233,7 +233,10 @@ export class CardTypeResource extends FileResource {
   }
 
   // If value from 'customFields' is removed, remove it also from 'optionallyVisible' and 'alwaysVisible' arrays.
-  private removeValueFromOtherArrays<Type>(op: Operation<Type>) {
+  private removeValueFromOtherArrays<Type>(
+    op: Operation<Type>,
+    content: CardType,
+  ) {
     // Update target can be a string, or an object. Of object, fetch only 'name'
     // todo: fetching 'name' or using string as name could be function in resource base class.
     const target = (op as RemoveOperation<Type>).target as Type;
@@ -242,8 +245,8 @@ export class CardTypeResource extends FileResource {
       field = { name: target['name' as keyof Type] };
     }
     const fieldName = (field ? field.name : target) as string;
-    this.removeValue(this.data.alwaysVisibleFields, fieldName);
-    this.removeValue(this.data.optionallyVisibleFields, fieldName);
+    this.removeValue(content.alwaysVisibleFields, fieldName);
+    this.removeValue(content.optionallyVisibleFields, fieldName);
   }
 
   // Sets content container values to be either '[]' or with proper values.
@@ -481,7 +484,7 @@ export class CardTypeResource extends FileResource {
     const existingName = this.content.name;
     await super.update(key, op);
 
-    const content = this.content as CardType;
+    const content = structuredClone(this.content) as CardType;
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
     } else if (key === 'alwaysVisibleFields') {
@@ -513,12 +516,15 @@ export class CardTypeResource extends FileResource {
         content.customFields as Type[],
       ) as CustomField[];
       if (op.name === 'remove') {
-        this.removeValueFromOtherArrays(op);
+        this.removeValueFromOtherArrays(op, content);
       }
+    } else if (key === 'description') {
+      content.description = super.handleScalar(op) as string;
+    } else if (key === 'displayName') {
+      content.displayName = super.handleScalar(op) as string;
     } else {
       throw new Error(`Unknown property '${key}' for CardType`);
     }
-
     await super.postUpdate(content, key, op);
 
     // Renaming this card type causes that references to its name must be updated.