@cyberismo/data-handler 0.0.7 → 0.0.9

package/src/resources/folder-resource.ts

@@ -11,8 +11,10 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { basename, join } from 'node:path';
-import { mkdir, rename, rm } from 'node:fs/promises';
+import { basename, dirname, join, normalize } from 'node:path';
+import { mkdir, readdir, readFile, rename, rm } from 'node:fs/promises';
+
+import { writeFileSafe } from '../utils/file-utils.js';
 
 import type { ResourceFolderType } from '../interfaces/project-interfaces.js';
 import {
@@ -27,6 +29,7 @@ import {
   sortCards,
 } from './file-resource.js';
 import type { ResourceContent } from '../interfaces/resource-interfaces.js';
+import { VALID_FOLDER_RESOURCE_FILES } from '../utils/constants.js';
 
 export {
   type Card,
@@ -73,6 +76,15 @@ export class FolderResource extends FileResource {
     await rm(this.internalFolder, { recursive: true, force: true });
   }
 
+  // Get (resource folder) type name
+  protected get getType() {
+    return super.getType;
+  }
+
+  protected get logger() {
+    return super.getLogger(this.getType);
+  }
+
   protected initialize(): void {
     super.initialize();
 
@@ -98,6 +110,51 @@ export class FolderResource extends FileResource {
     return super.show();
   }
 
+  /**
+   * Shows the content of a file in the resource.
+   * @param fileName Name of the file to show.
+   * @returns the content of the file.
+   */
+  public async showFile(fileName: string): Promise<string> {
+    const filePath = join(this.internalFolder, fileName);
+    return readFile(filePath, 'utf8');
+  }
+
+  /**
+   * Shows all file names in the resource.
+   * @returns all file names in the resource.
+   */
+  public async showFileNames(): Promise<string[]> {
+    const files = await readdir(this.internalFolder);
+    return files.filter((file) => VALID_FOLDER_RESOURCE_FILES.includes(file));
+  }
+
+  /**
+   * Updates a file in the resource.
+   * @param fileName The name of the file to update.
+   * @param changedContent The new content for the file.
+   */
+  public async updateFile(fileName: string, changedContent: string) {
+    const filePath = join(this.internalFolder, fileName);
+
+    // Do not allow updating file in other directories
+    const normalizedFilePath = normalize(filePath);
+    const normalizedInternalFilePath = normalize(this.internalFolder);
+    if (dirname(normalizedFilePath) !== normalizedInternalFilePath) {
+      throw new Error(`File '${fileName}' is not in the resource`);
+    }
+
+    // This makes sure that the file is in the resource folder.
+    if (basename(normalizedFilePath) !== fileName) {
+      throw new Error(`File '${fileName}' is not in the resource`);
+    }
+    // check if the file is whitelisted
+    if (!VALID_FOLDER_RESOURCE_FILES.includes(fileName)) {
+      throw new Error(`File '${fileName}' is not whitelisted`);
+    }
+
+    await writeFileSafe(filePath, changedContent, { flag: 'w' });
+  }
   /**
    * Updates resource.
    * @param key Key to modify

package/src/resources/graph-model-resource.ts

@@ -150,7 +150,7 @@ export class GraphModelResource extends FolderResource {
 
     await super.update(key, op);
 
-    const content = { ...(this.content as GraphModel) };
+    const content = structuredClone(this.content) as GraphModel;
 
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;

package/src/resources/graph-view-resource.ts

@@ -144,7 +144,7 @@ export class GraphViewResource extends FolderResource {
 
     await super.update(key, op);
 
-    const content = { ...(this.content as GraphView) };
+    const content = structuredClone(this.content) as GraphView;
 
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;

package/src/resources/report-resource.ts

@@ -179,7 +179,7 @@ export class ReportResource extends FolderResource {
 
     await super.update(key, op);
 
-    const content = { ...(this.content as ReportMetadata) };
+    const content = structuredClone(this.content) as ReportMetadata;
 
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;

package/src/resources/resource-object.ts

@@ -21,9 +21,11 @@ import type {
   Card,
   ResourceFolderType,
 } from '../interfaces/project-interfaces.js';
+import type { Logger } from 'pino';
 import { type Project, ResourcesFrom } from '../containers/project.js';
 import type { ResourceContent } from '../interfaces/resource-interfaces.js';
 import type { ResourceName } from '../utils/resource-utils.js';
+import { getChildLogger } from '../utils/log-utils.js';
 
 // Possible operations to perform when doing "update"
 export type UpdateOperations = 'add' | 'change' | 'rank' | 'remove';
@@ -44,6 +46,7 @@ export type AddOperation<T> = BaseOperation<T> & {
 export type ChangeOperation<T> = BaseOperation<T> & {
   name: 'change';
   to: T;
+  mappingTable?: { stateMapping: Record<string, string> }; // Optional state mapping for workflow changes
 };
 
 // Move item in an array to new position.
@@ -81,6 +84,9 @@ export abstract class AbstractResource {
   protected abstract usage(cards?: Card[]): Promise<string[]>; // list of card keys or resource names where this resource is used in
   protected abstract validate(content?: object): Promise<void>; // validate the content
   protected abstract write(): Promise<void>; // write content to disk
+  // Abstract getters
+  protected abstract get getType(): string;
+  protected abstract getLogger(loggerName: string): Logger;
 }
 
 /**
@@ -110,6 +116,14 @@ export class ResourceObject extends AbstractResource {
   protected async show(): Promise<ResourceContent> {
     return {} as ResourceContent;
   }
+  protected get getType(): string {
+    return this.type;
+  }
+  protected getLogger(loggerName: string): Logger {
+    return getChildLogger({
+      module: loggerName,
+    });
+  }
   protected async update<Type>(_key: string, _op: Operation<Type>) {}
   protected async usage(_cards?: Card[]): Promise<string[]> {
     return [];

package/src/resources/template-resource.ts

@@ -146,7 +146,7 @@ export class TemplateResource extends FolderResource {
 
     await super.update(key, op);
 
-    const content = { ...(this.content as TemplateMetadata) };
+    const content = structuredClone(this.content) as TemplateMetadata;
 
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;

package/src/resources/workflow-resource.ts

@@ -82,12 +82,8 @@ export class WorkflowResource extends FileResource {
 
   // 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;
+    const content = structuredClone(this.content) as Workflow;
+    const stateName = this.targetName(op) as string;
     // Check that state can be changed to
     content.transitions = content.transitions.filter(
       (t) => t.toState !== stateName,
@@ -111,12 +107,8 @@ export class WorkflowResource extends FileResource {
   // 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;
+    const content = structuredClone(this.content) as Workflow;
+    const stateName = this.targetName(op) as string;
 
     // If there is no replacement value, remove all transitions "to" and "from" this state.
     if (!op.replacementValue) {
@@ -154,6 +146,42 @@ export class WorkflowResource extends FileResource {
     }
   }
 
+  // Returns target name irregardless of the type
+  private targetName(op: Operation<WorkflowState | WorkflowTransition>) {
+    const name = op.target.name ? op.target.name : op.target;
+    return name;
+  }
+
+  // Potentially updates the changed transition with current properties.
+  private async transitionObject(op: ChangeOperation<WorkflowTransition>) {
+    const content = structuredClone(this.content) as Workflow;
+    const targetTransitionName = this.targetName(op);
+    const currentTransition = content.transitions.filter(
+      (item) => item.name === targetTransitionName,
+    )[0];
+
+    if (currentTransition) {
+      op.to.fromState =
+        op.to.fromState.length === 0
+          ? currentTransition.fromState
+          : op.to.fromState;
+      op.to.toState = op.to.toState ?? currentTransition.toState;
+    }
+
+    if (
+      op.to.name === undefined ||
+      op.to.toState === undefined ||
+      op.to.fromState == undefined ||
+      op.to.fromState.length === 0
+    ) {
+      throw new Error(
+        `Cannot change transition '${targetTransitionName}' for workflow '${this.content.name}'.
+         Updated transition must have 'name', 'toState' and 'fromState' properties.`,
+      );
+    }
+    return op.to;
+  }
+
   // Check if operation is a string operation.
   private isStringOperation(op: Operation<unknown>): op is Operation<string> {
     return typeof op.target === 'string';
@@ -250,7 +278,7 @@ export class WorkflowResource extends FileResource {
 
     await super.update(key, op);
 
-    const content = { ...(this.content as Workflow) };
+    const content = structuredClone(this.content) as Workflow;
 
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
@@ -270,6 +298,33 @@ export class WorkflowResource extends FileResource {
       throw new Error(`Unknown property '${key}' for Workflow`);
     }
 
+    // If workflow transition is removed, then above call to 'handleArray' is all that is needed.
+
+    if (key === 'transitions' && op.name === 'change') {
+      // If workflow transition is changed, update to full object and change the content.
+      let changeOp: ChangeOperation<WorkflowTransition>;
+      if (this.isStringOperation(op)) {
+        const targetTransition = (this.content as Workflow).transitions.find(
+          (transition) => transition.name === op.target,
+        )!;
+        changeOp = {
+          name: 'change',
+          target: targetTransition as WorkflowTransition,
+          to: {
+            name: op.to,
+            toState: targetTransition.toState,
+            fromState: targetTransition.fromState,
+          },
+        };
+      } else {
+        changeOp = op as ChangeOperation<WorkflowTransition>;
+      }
+      const newTransition = await this.transitionObject(changeOp);
+      content.transitions = content.transitions.map((item) =>
+        item.name == newTransition.name ? newTransition : item,
+      );
+    }
+
     if (key === 'states' && op.name === 'remove') {
       // If workflow state is removed, remove all transitions "to" and "from" this state.
       let removeOp: RemoveOperation<WorkflowState>;

package/src/svg/index.ts

@@ -0,0 +1,15 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  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/>.
+*/
+export * from './scoreCard.js';
+export * from './percentage.js';

package/src/svg/lib.ts

@@ -0,0 +1,31 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  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 pixelWidth from 'string-pixel-width';
+
+/**
+ * Measures the width of a text string
+ * @param text - The text to measure
+ * @param font - The font to use
+ * @param size - The size of the font
+ * @param bold - Whether the text is bold
+ * @returns The width of the text
+ */
+export function measureTextWidth(
+  text: string,
+  font: string,
+  size: number,
+  bold = false,
+): number {
+  return pixelWidth(text, { font, size, bold });
+}

package/src/svg/percentage.ts

@@ -0,0 +1,97 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  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/>.
+*/
+
+interface PercentageOptions {
+  title: string;
+  value: number;
+  legend: string;
+  colour?: 'blue' | 'green' | 'yellow' | 'red' | 'orange' | 'purple';
+}
+
+const SIZE = 160;
+const STROKE = 18;
+const R = (SIZE - STROKE) / 2;
+const CIRC = 2 * Math.PI * R;
+const TITLE_HEIGHT = 70; // Space for the title above the donut
+const EXTRA_WIDTH = 80; // Extra width for the title area
+const SVG_WIDTH = SIZE + EXTRA_WIDTH;
+// SVG_HEIGHT will be calculated dynamically below
+const TITLE_FONT_SIZE = 22;
+const VALUE_FONT_SIZE = 32;
+const LEGEND_FONT_SIZE = 18;
+const DONUT_COLOR_RED = '#b22217';
+const TITLE_Y = 36;
+const LINE_SPACING = 1.2;
+
+/**
+ * Splits a string into lines of up to maxLen characters, breaking at spaces.
+ */
+function wrapText(text: string, maxLen: number): string[] {
+  const words = text.split(' ');
+  const lines: string[] = [];
+  let current = '';
+  for (const word of words) {
+    if ((current + (current ? ' ' : '') + word).length > maxLen) {
+      if (current) lines.push(current);
+      current = word;
+    } else {
+      current += (current ? ' ' : '') + word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines;
+}
+
+/**
+ * Creates a percentage widget as an SVG
+ * @param options - The options for the percentage
+ * @returns The widget as an SVG
+ */
+export function percentage(options: PercentageOptions): string {
+  const { title, value, legend, colour = 'blue' } = options;
+  const offset = CIRC * (1 - value / 100);
+  const DONUT_COLOR = colour === 'red' ? DONUT_COLOR_RED : colour;
+  const titleLines = wrapText(title, 24);
+  const donutYOffset =
+    TITLE_Y +
+    (titleLines.length - 1) * TITLE_FONT_SIZE * LINE_SPACING +
+    TITLE_FONT_SIZE +
+    24;
+  const donutCenterY = donutYOffset + SIZE / 2 - TITLE_HEIGHT / 2;
+  const dynamicSVGHeight = donutYOffset + SIZE / 2 + R + 20;
+  return `
+<svg width="${SVG_WIDTH}" height="${dynamicSVGHeight}" viewBox="0 0 ${SVG_WIDTH} ${dynamicSVGHeight}" xmlns="http://www.w3.org/2000/svg">
+  <title>${title}</title>
+
+  <!-- Visible Title (wrapped) -->
+  <text x="${SVG_WIDTH / 2}" y="${TITLE_Y}" text-anchor="middle" font-size="${TITLE_FONT_SIZE}" font-weight="bold">
+    ${titleLines.map((line, i) => `<tspan x='${SVG_WIDTH / 2}' dy='${i === 0 ? 0 : LINE_SPACING}em'>${line}</tspan>`).join('')}
+  </text>
+
+  <!-- Background track -->
+  <circle cx="${SVG_WIDTH / 2}" cy="${donutCenterY}" r="${R}"
+          fill="none" stroke="#eee" stroke-width="${STROKE}" />
+
+  <!-- Progress arc -->
+  <circle cx="${SVG_WIDTH / 2}" cy="${donutCenterY}" r="${R}"
+          fill="none" stroke="${DONUT_COLOR}" stroke-width="${STROKE}"
+          stroke-dasharray="${CIRC}" stroke-dashoffset="${offset}"
+          stroke-linecap="butt"
+          transform="rotate(-90 ${SVG_WIDTH / 2} ${donutCenterY})" />
+
+  <!-- Numbers -->
+  <text x="${SVG_WIDTH / 2}" y="${donutCenterY - 8}" text-anchor="middle" font-size="${VALUE_FONT_SIZE}" font-weight="bold">${value}%</text>
+  <text x="${SVG_WIDTH / 2}" y="${donutCenterY + 20}" text-anchor="middle" font-size="${LEGEND_FONT_SIZE}">${legend}</text>
+</svg>
+`;
+}

package/src/svg/scoreCard.ts

@@ -0,0 +1,88 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  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 { measureTextWidth } from './lib.js';
+
+// Padding on y-axis
+const PADDING = 24;
+// font used to estimate text width
+const FONT_FAMILY = 'Helvetica';
+const TITLE_SIZE = 16;
+const VALUE_SIZE = 48;
+const UNIT_SIZE = 24;
+const CAPTION_SIZE = 14;
+const UNIT_OFFSET = 3;
+const LINE_GAP_TITLE = 16;
+const LINE_GAP_CAPTION = 16;
+
+/**
+ * Options for the score card
+ * @param title - The title of the score card
+ * @param value - The value of the score card
+ * @param unit - The unit of the score card
+ * @param legend - The legend of the score card
+ */
+export interface ScoreCardOptions {
+  value: number;
+  title?: string;
+  legend?: string;
+  unit?: string;
+}
+
+/**
+ * Creates an SVG score card
+ * @param options - The options for the score card
+ * @returns The SVG score card
+ */
+export function scoreCard(options: ScoreCardOptions): string {
+  const { title = '', value, unit = '', legend = '' } = options;
+
+  const titleWidth = measureTextWidth(title, FONT_FAMILY, TITLE_SIZE, false);
+  const valueWidth = measureTextWidth(
+    String(value),
+    FONT_FAMILY,
+    VALUE_SIZE,
+    true,
+  );
+  const unitWidth = measureTextWidth(unit, FONT_FAMILY, UNIT_SIZE, false);
+  const captionWidth = measureTextWidth(
+    legend,
+    FONT_FAMILY,
+    CAPTION_SIZE,
+    false,
+  );
+
+  const valueLineWidth = valueWidth + unitWidth + UNIT_OFFSET;
+  const maxTextWidth = Math.max(titleWidth, valueLineWidth, captionWidth);
+
+  const width = Math.ceil(maxTextWidth + PADDING * 2);
+
+  const titleHeight = title.length > 0 ? TITLE_SIZE + LINE_GAP_TITLE : 0;
+  const valueHeight = VALUE_SIZE;
+  const captionHeight = legend.length > 0 ? CAPTION_SIZE + LINE_GAP_CAPTION : 0;
+
+  const textBlockHeight = titleHeight + valueHeight + captionHeight;
+
+  const height = Math.ceil(textBlockHeight + PADDING * 2);
+
+  const svgContent = `<svg class="card" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">
+    <rect rx="8" ry="8" fill="#fff" stroke="#dfe4ea" stroke-width="3" width="${width}" height="${height}"/>
+    <g text-anchor="middle">
+      <text class="title" x="${width / 2}" y="${TITLE_SIZE / 2 + PADDING}" font-size="${TITLE_SIZE}" font-weight="400" fill="#001829" dominant-baseline="middle">${title}</text>
+      <text class="value" x="${width / 2}" y="${titleHeight + VALUE_SIZE / 2 + PADDING}" font-size="${VALUE_SIZE}" font-weight="700" fill="#333" dominant-baseline="middle">${value}<tspan class="unit" font-size="${UNIT_SIZE}" font-weight="400" dx="${UNIT_OFFSET}">${unit}</tspan></text>
+      <text class="caption" x="${width / 2}" y="${titleHeight + valueHeight + LINE_GAP_CAPTION + CAPTION_SIZE / 2 + PADDING}" font-size="${CAPTION_SIZE}" font-weight="400" fill="#999" dominant-baseline="middle">${legend}</text>
+    </g>
+  </svg>`;
+
+  return svgContent;
+}

package/src/types/queries.ts

@@ -61,11 +61,6 @@ export interface DeniedOperationCollection {
 
 export interface BaseResult extends Record<string, unknown> {
   key: string;
-  labels: string[];
-  links: CalculationLink[];
-  notifications: Notification[];
-  policyChecks: PolicyCheckCollection;
-  deniedOperations: DeniedOperationCollection;
 }
 
 export interface ParseResult<T extends BaseResult> {
@@ -97,9 +92,15 @@ interface CardQueryResult extends BaseResult {
   rank: string;
   title: string;
   cardType: string;
+  cardTypeDisplayName: string;
   workflowState: string;
   lastUpdated: string;
-  fields?: CardQueryField[];
+  fields: CardQueryField[];
+  labels: string[];
+  links: CalculationLink[];
+  notifications: Notification[];
+  policyChecks: PolicyCheckCollection;
+  deniedOperations: DeniedOperationCollection;
 }
 interface FieldsToUpdateQueryResult extends BaseResult {
   updateFields: UpdateField[];
@@ -135,7 +136,7 @@ interface CardQueryField extends BaseResult {
   visibility: 'always' | 'optional';
   index: number;
   fieldDisplayName: string;
-  description: string;
+  fieldDescription: string;
   dataType: DataType;
   isCalculated: boolean;
   value: string | number | boolean | null | EnumValue | ListValueItem[];

package/src/types/string-pixel-width.d.ts

@@ -0,0 +1,23 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  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/>.
+*/
+declare module 'string-pixel-width' {
+  interface PixelWidthOptions {
+    font?: string;
+    size?: number;
+    bold?: boolean;
+    italic?: boolean;
+  }
+  function pixelWidth(text: string, options?: PixelWidthOptions): number;
+  export default pixelWidth;
+}

package/src/utils/card-utils.ts

@@ -81,3 +81,16 @@ export const sortCards = (a: string, b: string) => {
   if (aParts[1] < bParts[1]) return -1;
   return 0;
 };
+
+/**
+ * Returns module name from card key
+ * @param cardKey card key
+ * @returns module name
+ */
+export const moduleNameFromCardKey = (cardKey: string) => {
+  const parts = cardKey.split('_');
+  if (parts.length !== 2) {
+    throw new Error(`Invalid card key: ${cardKey}`);
+  }
+  return parts[0];
+};