@cyberismo/data-handler 0.0.2

package/src/interfaces/project-interfaces.ts

@@ -0,0 +1,208 @@
+/**
+    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/>.
+*/
+
+import type { Link, TemplateConfiguration } from './resource-interfaces.js';
+
+// Single card; either in project or in template.
+export interface Card {
+  key: string;
+  path: string;
+  content?: string;
+  metadata?: CardMetadata;
+  parent?: string;
+  children: Card[];
+  attachments: CardAttachment[];
+}
+
+// Attachment details
+export interface CardAttachment {
+  card: string;
+  path: string;
+  fileName: string;
+  mimeType: string | null;
+}
+
+// When cards are listed using 'show cards'
+export interface CardListContainer {
+  name: string;
+  type: string;
+  cards: string[];
+}
+// Remember to add all these keys to utils/constants.ts
+export interface PredefinedCardMetadata {
+  title: string;
+  cardType: string;
+  workflowState: string;
+  rank: string;
+  lastTransitioned?: string;
+  lastUpdated?: string;
+  templateCardKey?: string;
+}
+
+// todo: do we need in the future separation between module-template-cards and local template-cards
+export enum CardLocation {
+  all = 'all',
+  projectOnly = 'project',
+  templatesOnly = 'local',
+}
+
+// Card's index.json file content.
+export interface CardMetadata extends PredefinedCardMetadata {
+  labels?: string[];
+  links: Link[];
+  [key: string]: MetadataContent;
+}
+
+// Content in project (apart from cards) is either .schema files or cardsConfig.json.
+type ContentType = DotSchemaContent | ProjectSettings;
+
+// Single CSV row as read from a file.
+export type CSVRowRaw = {
+  [key: string]: string;
+};
+
+export interface DotSchemaItem {
+  id: string;
+  version: number;
+  file?: string;
+}
+export type DotSchemaContent = DotSchemaItem[];
+
+// Defines which details of a card are fetched.
+export interface FetchCardDetails {
+  attachments?: boolean;
+  calculations?: true;
+  children?: boolean;
+  content?: boolean;
+  contentType?: FileContentType;
+  metadata?: boolean;
+  parent?: boolean;
+}
+export interface ProjectFetchCardDetails extends FetchCardDetails {
+  location?: CardLocation;
+}
+
+export type FileContentType = 'adoc' | 'html';
+
+// Metadata content type.
+export type MetadataContent =
+  | bigint
+  | number
+  | boolean
+  | string
+  | string[]
+  | Link[]
+  | null
+  | undefined;
+
+// Module content
+export interface ModuleContent extends ProjectSettings {
+  path: string;
+  calculations: string[];
+  cardTypes: string[];
+  fieldTypes: string[];
+  graphModels: string[];
+  graphViews: string[];
+  linkTypes: string[];
+  reports: string[];
+  templates: string[];
+  workflows: string[];
+}
+
+// Files in project in addition to cards (.schema files and cardsConfig.json).
+export interface ProjectFile {
+  content: ContentType;
+  path: string;
+  name: string;
+}
+
+// Project metadata details. @todo - this overlaps the above; check & merge
+export interface ProjectMetadata {
+  name: string;
+  path: string;
+  prefix: string;
+  modules: string[];
+  numberOfCards: number;
+}
+
+// Project's settings (=cardsConfig.json).
+export interface ProjectSettings {
+  cardKeyPrefix: string;
+  name: string;
+  modules: ModuleSetting[];
+}
+
+// Module configuration.
+export interface ModuleSetting extends ModuleSettingOptions {
+  name: string;
+  location: string;
+}
+
+export interface ModuleSettingOptions {
+  branch?: string;
+  private?: boolean;
+}
+
+// Resources that are possible to remove.
+export type RemovableResourceTypes =
+  | 'attachment'
+  | 'card'
+  | 'cardType'
+  | 'fieldType'
+  | 'graphModel'
+  | 'graphView'
+  | 'link'
+  | 'linkType'
+  | 'module'
+  | 'report'
+  | 'template'
+  | 'workflow'
+  | 'label';
+
+// Project resource, such as workflow, template or card type as file system object.
+export interface Resource {
+  name: string;
+  path: string;
+}
+
+// Resources that have own folders.
+export type ResourceFolderType =
+  | 'calculations'
+  | 'cardTypes'
+  | 'fieldTypes'
+  | 'graphModels'
+  | 'graphViews'
+  | 'linkTypes'
+  | 'modules'
+  | 'reports'
+  | 'templates'
+  | 'workflows';
+
+// All resource types; both singular and plural.
+export type ResourceTypes =
+  | RemovableResourceTypes
+  | ResourceFolderType
+  | 'attachments'
+  | 'calculation'
+  | 'cards'
+  | 'label'
+  | 'labels'
+  | 'links'
+  | 'modules'
+  | 'project'
+  | 'projects';
+
+// Re-export Template Configuration to avoid unnecessary changes to other files.
+export { TemplateConfiguration };
+
+// Name for a card (consists of prefix and a random 8-character base36 string; e.g. 'test_abcd1234')
+export const CardNameRegEx = new RegExp(/^[a-z]+_[0-9a-z]+$/);

package/src/interfaces/request-status-interfaces.ts

@@ -0,0 +1,30 @@
+/**
+    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/>.
+*/
+
+enum httpStatusCode {
+  Info = 100,
+  OK = 200,
+  BAD = 400,
+  SERVER_ERROR = 500,
+}
+export interface requestStatus {
+  statusCode: httpStatusCode;
+  message?: string;
+  affectsCards?: string[];
+  payload?: object | attachmentPayload;
+}
+
+// todo: this should be someplace else
+export interface attachmentPayload {
+  fileBuffer: Buffer;
+  mimeType: string;
+}

package/src/interfaces/resource-interfaces.ts

@@ -0,0 +1,179 @@
+/**
+    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/>.
+*/
+
+import type { Schema } from 'jsonschema';
+
+/**
+ * Each resource represents a file (or a folder in some cases) with metadata stored
+ * in JSON file. Name of the file is the name of the resource. Each resource is expected to be
+ * in a correct place in folder structure.
+ */
+
+// Calculation does not have own metadata.
+export type CalculationMetadata = ResourceBaseMetadata;
+
+// Card type content.
+export interface CardType extends ResourceBaseMetadata {
+  workflow: string;
+  customFields: CustomField[];
+  alwaysVisibleFields: string[];
+  optionallyVisibleFields: string[];
+}
+
+// Custom field
+export interface CustomField {
+  name: string;
+  description?: string;
+  displayName?: string;
+  isCalculated: boolean;
+}
+
+// Supported data types.
+export type DataType =
+  | 'boolean'
+  | 'date'
+  | 'dateTime'
+  | 'enum'
+  | 'integer'
+  | 'list'
+  | 'longText'
+  | 'number'
+  | 'person'
+  | 'shortText';
+
+// Custom field enum value
+export interface EnumDefinition {
+  enumValue: string;
+  enumDisplayValue?: string;
+  enumDescription?: string;
+}
+
+// Field type content.
+export interface FieldType extends ResourceBaseMetadata {
+  displayName?: string;
+  fieldDescription?: string;
+  dataType: DataType;
+  enumValues?: Array<EnumDefinition>;
+}
+
+// Graph model content.
+export interface GraphModelMetadata extends ResourceBaseMetadata {
+  category?: string;
+  description?: string;
+  displayName: string;
+}
+
+export interface GraphModel extends GraphModelMetadata {
+  calculationFile: string;
+}
+
+// Graph view content.
+export interface GraphViewMetadata extends ResourceBaseMetadata {
+  category?: string;
+  description?: string;
+  displayName: string;
+}
+
+export interface GraphView extends GraphViewMetadata {
+  handleBarFile: string;
+}
+
+// Link content.
+export interface Link {
+  linkType: string;
+  cardKey: string;
+  linkDescription?: string;
+}
+
+// Link type resource.
+export interface LinkType extends ResourceBaseMetadata {
+  outboundDisplayName: string;
+  inboundDisplayName: string;
+  sourceCardTypes: string[];
+  destinationCardTypes: string[];
+  enableLinkDescription: boolean;
+}
+
+// Report resource.
+export interface Report {
+  name: string;
+  metadata: ReportMetadata;
+  contentTemplate: string;
+  queryTemplate: string;
+  schema?: Schema;
+}
+
+// Metadata for report
+export interface ReportMetadata extends ResourceBaseMetadata {
+  displayName: string;
+  description: string;
+  category: string;
+}
+
+// Base interface for all resources.
+export interface ResourceBaseMetadata {
+  name: string;
+  usedIn?: string[];
+}
+
+// All resources metadata content.
+export type ResourceContent =
+  | CardType
+  | FieldType
+  | GraphModel
+  | GraphView
+  | LinkType
+  | ReportMetadata
+  | TemplateMetadata
+  | Workflow;
+
+// Template configuration details.
+export interface TemplateConfiguration {
+  name: string;
+  path: string;
+  numberOfCards: number;
+  metadata: TemplateMetadata;
+}
+
+// Template configuration content details.
+export interface TemplateMetadata extends ResourceBaseMetadata {
+  displayName?: string;
+  description?: string;
+  category?: string;
+}
+
+// Workflow's json file content.
+export interface Workflow extends ResourceBaseMetadata {
+  states: WorkflowState[];
+  transitions: WorkflowTransition[];
+}
+
+// Workflow state categories.
+export enum WorkflowCategory {
+  initial = 'initial',
+  active = 'active',
+  closed = 'closed',
+  none = 'none',
+}
+
+// Workflow state.
+export interface WorkflowState {
+  name: string;
+  category?: WorkflowCategory;
+}
+
+// Workflow transition.
+export interface WorkflowTransition {
+  name: string;
+  fromState: string[];
+  toState: string;
+}

package/src/macros/base-macro.ts

@@ -0,0 +1,176 @@
+/**
+    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/>.
+*/
+
+import type {
+  HandlebarsOptions,
+  MacroGenerationContext,
+  MacroMetadata,
+  MacroTaskState,
+} from '../interfaces/macros.js';
+import { generateRandomString } from '../utils/random.js';
+import { handleMacroError } from './index.js';
+import type TaskQueue from './task-queue.js';
+
+abstract class BaseMacro {
+  private globalId: string;
+  private localCounter: number = 0;
+
+  constructor(
+    protected macroMetadata: MacroMetadata,
+    private readonly tasks: TaskQueue,
+  ) {
+    // Set a unique global id for each instance of the macro
+    this.globalId = `${generateRandomString(36, 10)}`;
+  }
+
+  protected abstract handleInject(
+    context: MacroGenerationContext,
+    input: unknown,
+  ): Promise<string>;
+
+  protected abstract handleStatic(
+    context: MacroGenerationContext,
+    input: unknown,
+  ): Promise<string>;
+
+  protected abstract handleValidate(input: unknown): void;
+
+  public get metadata() {
+    return this.macroMetadata;
+  }
+
+  private findDependencies(input: string): MacroTaskState[] {
+    // Define a regex pattern to identify dependencies in the input string.
+    const dependencyPattern = /<<macro::([a-zA-Z0-9_-]+)::([0-9]+)>>/g;
+
+    const dependencies: MacroTaskState[] = [];
+
+    let match;
+    while ((match = dependencyPattern.exec(input)) !== null) {
+      const [placeholder, globalId, localId] = match;
+
+      // Retrieve the task corresponding to the globalId and localId
+      const task = this.tasks.find(globalId, parseInt(localId, 10));
+
+      if (task) {
+        dependencies.push(task);
+      } else {
+        console.warn(
+          `Dependency not found for placeholder: ${placeholder} (globalId: ${globalId}, localId: ${localId})`,
+        );
+      }
+    }
+
+    return dependencies;
+  }
+
+  private generatePlaceholder() {
+    const localId = this.localCounter++;
+    return {
+      localId,
+      placeholder: `<<macro::${this.globalId}::${localId}>>`,
+    };
+  }
+
+  /**
+   * Function responsible for starting the promise and storing it along with its localId.
+   */
+  public invokeMacro = (
+    context: MacroGenerationContext,
+    options: HandlebarsOptions,
+  ) => {
+    // Create a unique localId for each invocation
+    const { placeholder, localId } = this.generatePlaceholder();
+
+    const rawInput = options.fn(this);
+    let input = '{' + rawInput + '}';
+
+    if (context.mode === 'validate') {
+      try {
+        this.handleValidate(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}`;
+          throw new Error(errorMessage);
+        }
+        throw error;
+      }
+      return;
+    }
+
+    // Extract dependencies
+    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))
+      .then(() => {
+        for (const dependency of dependencies) {
+          input = input.replace(
+            dependency.placeholder,
+            dependency.promiseResult || '',
+          );
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(input);
+        } catch {
+          return 'Invalid JSON';
+        }
+
+        // Select the function to execute based on context mode
+        const functionToCall =
+          context.mode === 'inject' ? this.handleInject : this.handleStatic;
+
+        // Execute the function and handle its result
+        return functionToCall(context, parsed);
+      })
+      .then((result) => {
+        const task = this.tasks.find(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 (task) {
+          task.promiseResult = handleMacroError(
+            err,
+            this.metadata.name,
+            context,
+          );
+        } else {
+          console.error(
+            `Error handling task for macro ${this.metadata.name}, local id ${localId}:`,
+            err,
+          );
+        }
+      });
+
+    // Store the task
+    this.tasks.push({
+      globalId: this.globalId,
+      localId,
+      promise,
+      placeholder,
+      promiseResult: null,
+      macro: this.macroMetadata.name,
+    });
+    // Return the placeholder
+    return placeholder;
+  };
+}
+
+export default BaseMacro;

package/src/macros/common.ts

@@ -0,0 +1,24 @@
+/**
+    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 report from './report/metadata.js';
+import scoreCard from './scoreCard/metadata.js';
+
+export const macroMetadata = {
+  createCards,
+  graph,
+  report,
+  scoreCard,
+};

package/src/macros/createCards/index.ts

@@ -0,0 +1,57 @@
+/**
+    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/>.
+*/
+
+import type { MacroOptions } from '../index.js';
+import { createHtmlPlaceholder, 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';
+
+export interface CreateCardsOptions extends MacroOptions {
+  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);
+  }
+
+  handleValidate = (input: unknown) => {
+    this.validate(input);
+  };
+
+  async handleStatic() {
+    // Buttons aren't supported in static mode
+    return '';
+  }
+
+  handleInject = async (_: MacroGenerationContext, input: unknown) => {
+    const options = this.validate(input);
+    return createHtmlPlaceholder(this.metadata, options);
+  };
+
+  private validate(input: unknown): CreateCardsOptions {
+    return validateMacroContent<CreateCardsOptions>(this.metadata, input);
+  }
+}
+
+export default CreateCardsMacro;

package/src/macros/createCards/metadata.ts

@@ -0,0 +1,21 @@
+/**
+    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/>.
+*/
+
+import type { MacroMetadata } from '../../interfaces/macros.js';
+
+const macroMetadata: MacroMetadata = {
+  name: 'createCards',
+  tagName: 'create-cards',
+  schema: 'createCardsMacroSchema',
+};
+
+export default macroMetadata;