@cyberismo/data-handler 0.0.19 → 0.0.21

package/src/macros/include/types.ts

@@ -12,21 +12,30 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+/**
+ * Include macro options.
+ * @param cardKey Card key of the card being included
+ * @param levelOffset A positive number will increase the level of headings.
+ *                    A negative value will decrease the level of headings in the included content.
+ * @param title Determines behaviour with the title that is in card metadata
+ *              include --> includes the title
+ *              exclude --> excludes the title
+ *              only --> includes title but does not import content
+ * @param whitespace Whether to trim leading and trailing whitespace
+ * @param escape Type of escaping to apply to the included content
+ *               json --> escapes for JSON strings
+ *               csv --> escapes for CSV fields
+ */
 export interface IncludeMacroOptions {
-  /**
-   * Card key of the card being included
-   */
   cardKey: string;
-  /**
-   * A positive number wil increase the level of headings and a negative alue will the level of headings in the included content
-   */
   levelOffset?: string;
-  /**
-   * Determines behaviour with the title that is in card metadata
-   * include --> includes the title
-   * exclude --> excludes the title
-   * only --> includes title but does not import content
-   */
   title?: 'include' | 'exclude' | 'only';
   pageTitles?: 'normal' | 'discrete';
+  /**
+   * Whether to trim initial and final whitespace and newlines from the output.
+   * Useful for generating non-AsciiDoc content such as JSON.
+   * Default is 'keep'.
+   */
+  whitespace?: 'keep' | 'trim';
+  escape?: 'json' | 'csv';
 }

package/src/macros/index.ts

@@ -249,6 +249,7 @@ export async function evaluateMacros(
     try {
       const compiled = handlebars.compile(preprocessRawBlocks(result), {
         strict: true,
+        ignoreStandalone: true,
       });
       result = compiled({ cardKey: context.cardKey });
 

package/src/resources/create-defaults.ts

@@ -115,7 +115,7 @@ export abstract class DefaultContent {
       displayName: '',
       dataType: dataType,
     } as FieldType;
-    if (dataType === 'enum') {
+    if (dataType === 'enum' || dataType === 'list') {
       value.enumValues = [{ enumValue: 'value1' }, { enumValue: 'value2' }];
     }
     return value;

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

@@ -188,13 +188,16 @@ export class FieldTypeResource extends FileResource<FieldType> {
         );
       }
       const newValue = (op as ChangeOperation<EnumDefinition>).to;
-      const foundTo = values.find(
-        (item) => (item as EnumDefinition).enumValue === newValue.enumValue,
-      );
-      if (foundTo) {
-        throw new Error(
-          `Cannot perform operation on 'enumValues'. Enum with value '${(op.to as EnumDefinition).enumValue}' already exists`,
+      // Only check for duplicates if the enumValue itself is being changed
+      if (newValue.enumValue !== targetValue.enumValue) {
+        const foundTo = values.find(
+          (item) => (item as EnumDefinition).enumValue === newValue.enumValue,
         );
+        if (foundTo) {
+          throw new Error(
+            `Cannot perform operation on 'enumValues'. Enum with value '${(op.to as EnumDefinition).enumValue}' already exists`,
+          );
+        }
       }
     }
     // Return the whole object; caller can just provide 'enumValue'.
@@ -431,6 +434,10 @@ export class FieldTypeResource extends FileResource<FieldType> {
         }
         content.dataType = super.handleScalar(op) as DataType;
       } else if (key === 'enumValues') {
+        // Initialize enumValues array if it doesn't exist
+        if (!content.enumValues) {
+          content.enumValues = [];
+        }
         if (op.name === 'add' || op.name === 'change' || op.name === 'remove') {
           const existingValue = this.enumValueExists<EnumDefinition>(
             op as Operation<EnumDefinition>,

package/src/resources/folder-resource.ts

@@ -19,6 +19,7 @@ import { isContentKey } from '../interfaces/resource-interfaces.js';
 import {
   filename,
   contentPropertyName,
+  ALL_FILE_MAPPINGS,
 } from '../interfaces/folder-content-interfaces.js';
 import { formatJson } from '../utils/json.js';
 import { VALID_FOLDER_RESOURCE_FILES } from '../utils/constants.js';
@@ -95,7 +96,7 @@ export abstract class FolderResource<
     for (const [fileName, fileContent] of contentFiles.entries()) {
       const key = contentPropertyName(fileName);
       if (key) {
-        const isJson = key === 'schema';
+        const isJson = key === ALL_FILE_MAPPINGS['parameterSchema.json'];
         content[key] = isJson ? JSON.parse(fileContent) : fileContent;
       }
     }
@@ -143,15 +144,28 @@ export abstract class FolderResource<
       throw new Error(`File '${fileName}' is not allowed to be updated`);
     }
 
-    await writeFileSafe(filePath, changedContent, { flag: 'w' });
+    // TODO: Updates should either use valid strings or allow for objects
+    const key = contentPropertyName(fileName);
+    const isJson = key === ALL_FILE_MAPPINGS['parameterSchema.json'];
+    let parsedContent: unknown = changedContent;
+    if (isJson) {
+      try {
+        parsedContent = JSON.parse(changedContent);
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : 'Unknown error';
+        throw new Error(`Invalid JSON content for '${key}' update: ${message}`);
+      }
+    }
+    const contentToWrite = isJson
+      ? formatJson(parsedContent as object)
+      : changedContent;
+
+    await writeFileSafe(filePath, contentToWrite, { flag: 'w' });
 
     // Update this resource's content
-    const key = contentPropertyName(fileName);
     if (key) {
-      const isJson = key === 'schema';
-      (this.resourceContent as Record<string, unknown>)[key] = isJson
-        ? JSON.parse(changedContent)
-        : changedContent;
+      (this.resourceContent as Record<string, unknown>)[key] = parsedContent;
     }
   }
 

package/src/resources/workflow-resource.ts

@@ -78,16 +78,11 @@ export class WorkflowResource extends FileResource<Workflow> {
   }
 
   // Handle change of workflow state.
-  private async handleStateChange(op: ChangeOperation<WorkflowState>) {
-    const content = structuredClone(this.content);
+  private async handleStateChange(
+    content: Workflow,
+    op: ChangeOperation<WorkflowState>,
+  ) {
     const stateName = this.targetName(op) 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(
@@ -95,16 +90,26 @@ export class WorkflowResource extends FileResource<Workflow> {
          Updated state must have 'name' and 'category' properties.`,
       );
     }
-    // Update all cards that use this state.
+    // Rename transitions to use the new state name
     const toStateName = op.to.name;
-
+    content.transitions.forEach((t) => {
+      if (t.toState === stateName) {
+        t.toState = toStateName;
+      }
+      t.fromState = t.fromState.map((state) =>
+        state === stateName ? toStateName : state,
+      );
+    });
+    // Update all cards that use this state.
     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 = structuredClone(this.content);
+  private async handleStateRemoval(
+    content: Workflow,
+    op: RemoveOperation<WorkflowState>,
+  ) {
     const stateName = this.targetName(op) as string;
 
     // If there is no replacement value, remove all transitions "to" and "from" this state.
@@ -232,6 +237,28 @@ export class WorkflowResource extends FileResource<Workflow> {
     return super.create(newContent);
   }
 
+  /**
+   * Validates the content of the workflow resource.
+   * @param content Content to be validated.
+   * @throws if content is invalid.
+   */
+  public async validate(content?: Workflow) {
+    // Base class run basic schema checks
+    await super.validate(content);
+
+    const workflowContent = content ?? this.content;
+
+    const newCardTransitions = workflowContent.transitions.filter(
+      (t) => t.fromState.includes('') || t.fromState.length === 0,
+    );
+
+    if (newCardTransitions.length !== 1) {
+      throw new Error(
+        `Workflow '${workflowContent.name}' must have exactly one transition from "New Card" (empty fromState), found ${newCardTransitions.length}.`,
+      );
+    }
+  }
+
   /**
    * Renames the object and the file.
    * @param newName New name for the resource.
@@ -329,11 +356,13 @@ export class WorkflowResource extends FileResource<Workflow> {
           removeOp = {
             name: 'remove',
             target: toBeRemovedState as WorkflowState,
+            replacementValue: (op as RemoveOperation<unknown>)
+              .replacementValue as WorkflowState,
           };
         } else {
           removeOp = op as RemoveOperation<WorkflowState>;
         }
-        await this.handleStateRemoval(removeOp);
+        await this.handleStateRemoval(content, 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>;
@@ -349,7 +378,7 @@ export class WorkflowResource extends FileResource<Workflow> {
         } else {
           changeOp = op as ChangeOperation<WorkflowState>;
         }
-        await this.handleStateChange(changeOp);
+        await this.handleStateChange(content, changeOp);
       }
 
       await super.postUpdate(content, updateKey, op);

package/src/svg/percentage.ts

@@ -71,10 +71,14 @@ export function percentage(options: PercentageOptions): string {
   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">
+  <style>
+    .percentage-text { fill: var(--joy-palette-text-primary, #333); }
+    .percentage-legend { fill: var(--joy-palette-text-secondary, #666); }
+  </style>
   <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">
+  <text class="percentage-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>
 
@@ -90,8 +94,8 @@ export function percentage(options: PercentageOptions): string {
           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>
+  <text class="percentage-text" x="${SVG_WIDTH / 2}" y="${donutCenterY - 8}" text-anchor="middle" font-size="${VALUE_FONT_SIZE}" font-weight="bold">${value}%</text>
+  <text class="percentage-legend" x="${SVG_WIDTH / 2}" y="${donutCenterY + 20}" text-anchor="middle" font-size="${LEGEND_FONT_SIZE}">${legend}</text>
 </svg>
 `;
 }

package/src/svg/scoreCard.ts

@@ -76,11 +76,17 @@ export function scoreCard(options: ScoreCardOptions): string {
   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}"/>
+    <style>
+      .scorecard-bg { fill: var(--joy-palette-background-surface, #fff); stroke: var(--joy-palette-divider, #dfe4ea); }
+      .scorecard-title { fill: var(--joy-palette-text-primary, #001829); }
+      .scorecard-value { fill: var(--joy-palette-text-primary, #333); }
+      .scorecard-caption { fill: var(--joy-palette-text-tertiary, #999); }
+    </style>
+    <rect class="scorecard-bg" rx="8" ry="8" 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>
+      <text class="scorecard-title" x="${width / 2}" y="${TITLE_SIZE / 2 + PADDING}" font-size="${TITLE_SIZE}" font-weight="400" dominant-baseline="middle">${title}</text>
+      <text class="scorecard-value" x="${width / 2}" y="${titleHeight + VALUE_SIZE / 2 + PADDING}" font-size="${VALUE_SIZE}" font-weight="700" dominant-baseline="middle">${value}<tspan class="unit" font-size="${UNIT_SIZE}" font-weight="400" dx="${UNIT_OFFSET}">${unit}</tspan></text>
+      <text class="scorecard-caption" x="${width / 2}" y="${titleHeight + valueHeight + LINE_GAP_CAPTION + CAPTION_SIZE / 2 + PADDING}" font-size="${CAPTION_SIZE}" font-weight="400" dominant-baseline="middle">${legend}</text>
     </g>
   </svg>`;
 

package/src/types/queries.ts

@@ -94,7 +94,7 @@ interface CardQueryResult extends BaseResult {
   cardType: string;
   cardTypeDisplayName: string;
   workflowState: string;
-  lastUpdated: string;
+  lastUpdated?: string;
   fields: CardQueryField[];
   labels: string[];
   links: CalculationLink[];

package/src/utils/csv.ts

@@ -14,6 +14,18 @@ import { readFile } from 'node:fs/promises';
 import { parse } from 'csv-parse/sync';
 import type { CSVRowRaw } from '../interfaces/project-interfaces.js';
 
+/**
+ * Escapes a string for use as a CSV field.
+ * Escapes double quotes by doubling them. The caller is responsible for
+ * wrapping the result in quotes.
+ * @param str The string to escape
+ * @returns The escaped string (without surrounding quotes)
+ */
+export function escapeCsvField(str: string): string {
+  // Escape double quotes by doubling them
+  return str.replace(/"/g, '""');
+}
+
 /**
  * Reads a CSV file and returns its content as an array of objects.
  * @param file Path to the CSV file.

package/src/utils/json.ts

@@ -15,6 +15,29 @@
 import { readFileSync } from 'node:fs';
 import { type FileHandle, readFile, writeFile } from 'node:fs/promises';
 
+/**
+ * Escapes a string for use as a JSON string value.
+ * Escapes double quotes, backslashes, and control characters.
+ * @param content The string to escape
+ * @returns The escaped string suitable for use in JSON
+ */
+export function escapeJsonString(content: string): string {
+  return JSON.stringify(content).slice(1, -1);
+}
+
+/**
+ * Format an object with JSON.stringify
+ *
+ * The purpose of this function is to format the JSON output in a centralised function
+ * so that the format can be controlled in a single location.
+ *
+ * @param json JSON object to format.
+ * @returns Formatted JSON string
+ */
+export function formatJson(json: object) {
+  return JSON.stringify(json, trimReplacer, 4);
+}
+
 /**
  * Handles reading of a JSON file.
  * @param file file name (and path) to read.
@@ -79,19 +102,6 @@ export function trimReplacer(_: string, value: unknown) {
   return value;
 }
 
-/**
- * Format an object with JSON.stringify
- *
- * The purpose of this function is to format the JSON output in a centralised function
- * so that the format can be controlled in a single location.
- *
- * @param json JSON object to format.
- * @returns Formatted JSON string
- */
-export function formatJson(json: object) {
-  return JSON.stringify(json, trimReplacer, 4);
-}
-
 /**
  * Writes and formats a JSON file.
  * @param filename file name (and path) to write.

package/src/utils/report.ts

@@ -14,6 +14,8 @@ import type { CalculationEngine } from '../containers/project/calculation-engine
 import { registerEmptyMacros } from '../macros/index.js';
 import type { Context } from '../interfaces/project-interfaces.js';
 import { resourceName } from './resource-utils.js';
+import { escapeJsonString } from './json.js';
+import { escapeCsvField } from './csv.js';
 
 /**
  * Formats a value from a logic program for use to graphviz
@@ -125,6 +127,8 @@ export async function generateReportContent(
   }
   handlebars.registerHelper('isCustomField', isCustomField);
   handlebars.registerHelper('formatValue', formatValue);
+  handlebars.registerHelper('jsonEscape', escapeJsonString);
+  handlebars.registerHelper('csvEscape', escapeCsvField);
 
   return handlebars.compile(contentTemplate)({
     ...options,

package/src/utils/resource-utils.ts

@@ -30,6 +30,7 @@ const IDENTIFIER_INDEX = 2;
 // Valid resource name has three parts
 const RESOURCE_NAME_PARTS = 3;
 const RESOURCE_FOLDER_TYPES = [
+  'calculations',
   'graphModels',
   'graphViews',
   'reports',