@cyberismo/data-handler 0.0.6 → 0.0.8

package/src/resources/workflow-resource.ts

@@ -1,13 +1,15 @@
 /**
-    Cyberismo
-    Copyright © Cyberismo Ltd and contributors 2024
+  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/>.
+  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 {
@@ -22,6 +24,7 @@ import type {
   ChangeOperation,
   Operation,
   Project,
+  RemoveOperation,
   ResourceName,
 } from './file-resource.js';
 import {
@@ -46,6 +49,27 @@ export class WorkflowResource extends FileResource {
     this.initialize();
   }
 
+  // Collect all cards that use this workflow.
+  private async collectCardsUsingWorkflow(): Promise<Card[]> {
+    const cardTypes = await this.project.cardTypes(ResourcesFrom.localOnly);
+    const promises: Promise<Card[]>[] = [];
+    for (const cardType of cardTypes) {
+      const object = new CardTypeResource(
+        this.project,
+        resourceName(cardType.name),
+      );
+      if (
+        object.data &&
+        (object.data as CardType).workflow ===
+          resourceNameToString(this.resourceName)
+      ) {
+        // fetch all cards with card type
+        promises.push(this.collectCards({ metadata: true }, cardType.name));
+      }
+    }
+    return (await Promise.all(promises)).flat();
+  }
+
   // When resource name changes.
   private async handleNameChange(existingName: string) {
     await Promise.all([
@@ -56,6 +80,96 @@ export class WorkflowResource extends FileResource {
     await this.write();
   }
 
+  // Handle change of workflow state.
+  private async handleStateChange(op: ChangeOperation<WorkflowState>) {
+    const content = { ...(this.content as Workflow) };
+    const stateName = (
+      (op.target as WorkflowState).name
+        ? (op.target as WorkflowState).name
+        : op.target
+    ) as string;
+    // Check that state can be changed to
+    content.transitions = content.transitions.filter(
+      (t) => t.toState !== stateName,
+    );
+    content.transitions.forEach((t) => {
+      t.fromState = t.fromState.filter((state) => state !== stateName);
+    });
+    // validate that new state contains 'name' and 'category'
+    if (op.to.name === undefined || op.to.category === undefined) {
+      throw new Error(
+        `Cannot change state '${stateName}' for workflow '${this.content.name}'.
+         Updated state must have 'name' and 'category' properties.`,
+      );
+    }
+    // Update all cards that use this state.
+    const toStateName = op.to.name;
+
+    await this.updateCardStates(stateName, toStateName);
+  }
+
+  // Handle removal of workflow state.
+  // State can be removed with or without replacement.
+  private async handleStateRemoval(op: RemoveOperation<WorkflowState>) {
+    const content = { ...(this.content as Workflow) };
+    const stateName = (
+      (op.target as WorkflowState).name
+        ? (op.target as WorkflowState).name
+        : op.target
+    ) as string;
+
+    // If there is no replacement value, remove all transitions "to" and "from" this state.
+    if (!op.replacementValue) {
+      content.transitions = content.transitions.filter(
+        (t) => t.toState !== stateName,
+      );
+      content.transitions.forEach((t) => {
+        t.fromState = t.fromState.filter((state) => state !== stateName);
+      });
+    } else {
+      // Replace transitions "to" the removed state with the replacement state.
+      const replacementState = op.replacementValue;
+      const stateExists = content.states.some(
+        (state) => state.name === replacementState.name,
+      );
+      if (!stateExists) {
+        throw new Error(
+          `Cannot change to unknown state '${replacementState.name}' for Workflow`,
+        );
+      }
+
+      content.transitions.forEach((t) => {
+        if (t.toState === stateName) {
+          t.toState = replacementState.name;
+        }
+      });
+      // Replace transitions "from" the removed state with the replacement state.
+      content.transitions.forEach((t) => {
+        t.fromState = t.fromState.map((state) =>
+          state === stateName ? replacementState.name : state,
+        );
+      });
+      // Update all cards that use this state.
+      await this.updateCardStates(stateName, replacementState.name);
+    }
+  }
+
+  // Check if operation is a string operation.
+  private isStringOperation(op: Operation<unknown>): op is Operation<string> {
+    return typeof op.target === 'string';
+  }
+
+  // Update card states when state is changed
+  private async updateCardStates(oldState: string, newState: string) {
+    const cards = await this.collectCardsUsingWorkflow();
+    cards.forEach(async (card) => {
+      if (card.metadata?.workflowState === oldState) {
+        card.metadata.workflowState = newState;
+        await this.project.updateCardMetadata(card, card.metadata);
+      }
+    });
+  }
+
   // Update dependant card types.
   private async updateCardTypes(oldName: string) {
     const cardTypes = await this.project.cardTypes(ResourcesFrom.localOnly);
@@ -156,6 +270,39 @@ export class WorkflowResource extends FileResource {
       throw new Error(`Unknown property '${key}' for Workflow`);
     }
 
+    if (key === 'states' && op.name === 'remove') {
+      // If workflow state is removed, remove all transitions "to" and "from" this state.
+      let removeOp: RemoveOperation<WorkflowState>;
+      if (this.isStringOperation(op)) {
+        const toBeRemovedState = (this.content as Workflow).states.find(
+          (state) => state.name === op.target,
+        );
+        removeOp = {
+          name: 'remove',
+          target: toBeRemovedState as WorkflowState,
+        };
+      } else {
+        removeOp = op as RemoveOperation<WorkflowState>;
+      }
+      await this.handleStateRemoval(removeOp);
+    } else if (key === 'states' && op.name === 'change') {
+      // If workflow state is renamed, replace all transitions "to" and "from" the old state with new state.
+      let changeOp: ChangeOperation<WorkflowState>;
+      if (this.isStringOperation(op)) {
+        const toBeChangedState = (this.content as Workflow).states.find(
+          (state) => state.name === op.target,
+        );
+        changeOp = {
+          name: 'change',
+          target: toBeChangedState as WorkflowState,
+          to: { name: op.to },
+        };
+      } else {
+        changeOp = op as ChangeOperation<WorkflowState>;
+      }
+      await this.handleStateChange(changeOp);
+    }
+
     await super.postUpdate(content, key, op);
 
     // Renaming this workflow causes that references to its name must be updated.

package/src/types/queries.ts

@@ -1,13 +1,14 @@
 /**
-    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/>.
 */
 
 /**
@@ -134,7 +135,7 @@ interface CardQueryField extends BaseResult {
   visibility: 'always' | 'optional';
   index: number;
   fieldDisplayName: string;
-  fieldDescription: string;
+  description: string;
   dataType: DataType;
   isCalculated: boolean;
   value: string | number | boolean | null | EnumValue | ListValueItem[];

package/src/utils/clingo-fact-builder.ts

@@ -1,5 +1,5 @@
 import { INT32_MAX } from './constants.js';
-import { logger } from './log-utils.js';
+import { getChildLogger } from './log-utils.js';
 
 /**
     Cyberismo
@@ -40,6 +40,11 @@ export class ClingoFactBuilder {
   protected predicate: string;
   private end: string;
   private arguments: ClingoArgumentInternal[] = [];
+  private get logger() {
+    return getChildLogger({
+      module: 'clingoFactBuilder',
+    });
+  }
 
   constructor(predicate: string, end: string = '.') {
     this.predicate = predicate;
@@ -120,7 +125,7 @@ export class ClingoFactBuilder {
     } else if (typeof value === 'number') {
       let floored = Math.floor(value);
       if (floored !== value) {
-        logger.warn(
+        this.logger.warn(
           {
             value,
           },
@@ -130,7 +135,7 @@ export class ClingoFactBuilder {
 
       const exceedsInt32Max = floored > INT32_MAX;
       if (exceedsInt32Max || floored < -INT32_MAX) {
-        logger.warn(
+        this.logger.warn(
           {
             value,
           },

package/src/utils/clingo-facts.ts

@@ -1,13 +1,14 @@
 /**
-    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/>.
 */
 import { sep } from 'node:path';
 
@@ -249,6 +250,11 @@ export const createCardFacts = async (card: Card, project: Project) => {
       b.addLiteralArguments(card.key, parentsPath),
     );
   }
+  builder.addCustomFact(Facts.Common.FIELD, (b) =>
+    b
+      .addLiteralArgument(card.key)
+      .addArguments('container', isTemplateCard(card) ? 'template' : 'project'),
+  );
 
   return builder.buildAll();
 };
@@ -270,12 +276,12 @@ export const createFieldTypeFacts = (fieldType: FieldType) => {
       fieldType.displayName,
     );
 
-  if (fieldType.fieldDescription)
+  if (fieldType.description)
     builder.addFact(
       Facts.Common.FIELD,
       fieldType.name,
-      'fieldDescription',
-      fieldType.fieldDescription,
+      'description',
+      fieldType.description,
     );
 
   builder.addFact(

package/src/utils/constants.ts

@@ -1,20 +1,22 @@
-import type { PredefinedCardMetadata } from '../interfaces/project-interfaces.js';
-
-export const INT32_MAX = 2147483647; // 2^31-1
 /**
-    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.
+  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/>.
+*/
 
-    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.
+import type { PredefinedCardMetadata } from '../interfaces/project-interfaces.js';
 
-    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/>.
-*/
+export const INT32_MAX = 2147483647; // 2^31-1
 
 /**
- * These are names of the fields that are non-custom fields that present in metadata
+ * These are field names that are non-custom fields that present in metadata
  */
 export const PREDEFINED_FIELDS = [
   'rank',
@@ -23,8 +25,14 @@ export const PREDEFINED_FIELDS = [
   'workflowState',
   'lastUpdated',
   'lastTransitioned',
+  'templateCardKey',
 ] satisfies (keyof PredefinedCardMetadata)[];
 
+/**
+ * Checks if the given value is a predefined field.
+ * @param value The field name to check.
+ * @returns True if the value is a predefined field, false otherwise.
+ */
 export function isPredefinedField(
   value: string,
 ): value is keyof PredefinedCardMetadata {

package/src/utils/log-utils.ts

@@ -9,54 +9,33 @@
     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 pino, { type ChildLoggerOptions, type Logger } from 'pino';
 
-import { join } from 'path';
-import pino, { type TransportTargetOptions } from 'pino';
-import { fileURLToPath } from 'url';
-const LOG_FILE_LOCATION: string = join(
-  fileURLToPath(import.meta.url),
-  '../../../../../logs/data-handler.trace',
-);
+// This could be also a more generic interface, but since we use pino and this is an internal package, let's keep it simple
+// silent logger as default
+let _logger: Logger = pino.default({ level: 'silent' });
 
-function getLogger() {
-  const all: TransportTargetOptions[] = [
-    {
-      target: 'pino/file',
-      options: { destination: LOG_FILE_LOCATION, mkdir: true }, // trace file
-      level: 'trace',
-    },
-    {
-      target: 'pino-pretty',
-      level: process.env.LOG_LEVEL || 'debug',
-    },
-  ];
-
-  const [file, stdout] = all;
-
-  if (process.env.NODE_ENV === 'test') {
-    // While testing, we simply use stdout and info level by default
-    return pino.default({
-      level: process.env.LOG_LEVEL || 'info',
-      transport: stdout,
-    });
-  }
-  if (process.env.NODE_ENV === 'development') {
-    // In dev mode, only stdout and debug logs by default
-    return pino.default({
-      level: 'trace',
-      transport: {
-        targets: all,
-      },
-    });
-  }
-  return pino.default({
-    level: 'trace',
-    transport: file,
-  });
+export function setLogger(logger: Logger) {
+  _logger = logger;
+}
+/**
+ * Returns the logger instance.
+ */
+export function getLogger(): Logger {
+  return _logger;
+}
+/**
+ * Returns a child logger instance.
+ * @param context Context to add to the logger.
+ * @param options Options to pass to the logger.
+ * @returns Child logger instance.
+ */
+export function getChildLogger(
+  context: { module: string } & Record<string, unknown>,
+  options?: ChildLoggerOptions,
+): Logger {
+  return _logger.child(context, options);
 }
-
-export const logger = getLogger();
-
 /**
  * Returns error message string from an Error object.
  * @param error Error object

package/src/utils/report.ts

@@ -0,0 +1,86 @@
+/**
+    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 Handlebars from 'handlebars';
+import type { Calculate } from '../commands/index.js';
+import { registerEmptyMacros } from '../macros/index.js';
+
+/**
+ * Formats a value from a logic program for use to graphviz
+ * @param value - The value to format
+ * @returns The formatted value
+ */
+export function formatAttributeValue(value?: string) {
+  if (!value) {
+    return '';
+  }
+  // value is an html-like string
+  if (value.length > 1 && value.startsWith('<') && value.endsWith('>')) {
+    return value;
+  }
+  // value is a normal string and needs to be wrapped in quotes
+  return `"${value}"`;
+}
+
+/**
+ * Parameters for the core generation function
+ */
+interface GenerateReportContentParams {
+  calculate: Calculate;
+  contentTemplate: string;
+  queryTemplate: string;
+  options: Record<string, string>;
+  graph?: boolean;
+}
+
+/**
+ * Generates report content based on a report definition, project context, and options,
+ * by utilizing the ReportRunner class.
+ *
+ * @param params - The parameters for report generation.
+ * @returns The rendered report content as a string.
+ * @throws Error if the report definition is invalid, schema validation fails, or logic program execution fails.
+ */
+export async function generateReportContent(
+  params: GenerateReportContentParams,
+): Promise<string> {
+  const {
+    calculate,
+    contentTemplate,
+    queryTemplate,
+    graph,
+    options, // Destructure options
+  } = params;
+
+  const handlebars = Handlebars.create();
+
+  // Compile and execute the query template
+  const template = handlebars.compile(queryTemplate, {
+    strict: true,
+  });
+
+  const result = await calculate.runLogicProgram(template(options));
+
+  if (result.error) {
+    throw new Error(result.error);
+  }
+  // register empty macros so that other macros aren't touched yet
+  registerEmptyMacros(handlebars);
+
+  if (graph) {
+    handlebars.registerHelper('formatAttributeValue', formatAttributeValue);
+  }
+
+  return handlebars.compile(contentTemplate)({
+    ...options,
+    ...result,
+  });
+}

package/src/utils/resource-utils.ts

@@ -140,6 +140,10 @@ export function pathToResourceName(
   if (!identifier || !type || !prefix) {
     throw new Error(`invalid path: ${path}`);
   }
+  if (identifierIndex + 1 !== parts.length) {
+    throw new Error(`not a resource path: ${path}`);
+  }
+
   return {
     prefix: prefix,
     type: type,

package/src/utils/sanitize-svg.ts

@@ -25,22 +25,17 @@ const removeSvgWidthAndHeight = (node: Element) => {
 };
 
 /**
- * Sanitize an SVG Buffer and return a base64-encoded string
- * @param buffer - SVG content as a Buffer
+ * Sanitize an SVG string and return a base64-encoded string
+ * @param svg - SVG content as a string
  * @returns base64-encoded sanitized SVG string
  */
-export function sanitizeSvgBase64(buffer: Buffer): string {
+export function sanitizeSvgBase64(svg: string): string {
   const DOMPurify = createDOMPurify(window as unknown as WindowLike);
 
-  const dirty = buffer.toString('utf-8');
-
   DOMPurify.setConfig({ USE_PROFILES: { svg: true } });
   DOMPurify.addHook('afterSanitizeAttributes', removeSvgWidthAndHeight);
 
-  let cleaned = DOMPurify.sanitize(dirty);
-
-  // Remove link titles, quick fix for Clingraph/Graphviz generated titles for links that are quite strange
-  cleaned = cleaned.replace(/\s*xlink:title=(["']).*?\1/g, '');
+  const cleaned = DOMPurify.sanitize(svg);
 
   return Buffer.from(cleaned, 'utf-8').toString('base64');
 }

package/src/utils/validate.ts

@@ -11,7 +11,7 @@
 */
 import { type Schema, Validator } from 'jsonschema';
 import { DHValidationError, SchemaNotFound } from '../exceptions/index.js';
-import { schemas } from '@cyberismo/resources';
+import { schemas } from '@cyberismo/assets';
 
 /**
  * Validates a JSON object against a schema
@@ -40,7 +40,8 @@ export function validateJson<T>(
   if (!validator) {
     validator = new Validator();
     for (const schema of schemas) {
-      validator.addSchema(schema, schema.$id);
+      // For some reason, the draft-07 schema is not a valid Schema, so we need to cast it
+      validator.addSchema(schema as Schema, schema.$id);
     }
   }
 

package/dist/commands/export-site.d.ts

@@ -1,45 +0,0 @@
-/**
-  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 Calculate, type Show } from './index.js';
-import { Export } from './export.js';
-import type { Project } from '../containers/project.js';
-interface ExportOptions {
-    silent: boolean;
-}
-export declare class ExportSite extends Export {
-    private tmpDir;
-    private moduleDir;
-    private pagesDir;
-    private imagesDir;
-    private playbookDir;
-    private playbookFile;
-    private navFile;
-    private options;
-    constructor(project: Project, calculateCmd: Calculate, showCmd: Show);
-    private createCardsIndex;
-    private initDirectories;
-    private generate;
-    private createPlaybook;
-    private createDescriptor;
-    private initRepo;
-    private toAdocDirectoryAsContent;
-    private export;
-    /**
-     * Export the card tree as an Antora site
-     * @param destination Path where the site is generated
-     * @param cardKey Optional; If defined exports the card tree from underneath this card.
-     */
-    exportToSite(destination: string, cardKey?: string, options?: ExportOptions): Promise<string>;
-}
-export {};