@cyberismo/data-handler 0.0.2

package/src/resources/workflow-resource.ts

@@ -0,0 +1,205 @@
+/**
+    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 {
+  CardType,
+  Workflow,
+  WorkflowState,
+  WorkflowTransition,
+} from '../interfaces/resource-interfaces.js';
+import { CardTypeResource } from './card-type-resource.js';
+import type {
+  Card,
+  ChangeOperation,
+  Operation,
+  Project,
+  ResourceName,
+} from './file-resource.js';
+import {
+  DefaultContent,
+  FileResource,
+  resourceNameToString,
+  sortCards,
+} from './folder-resource.js';
+import { ResourcesFrom } from '../containers/project.js';
+import { resourceName } from './file-resource.js';
+
+/**
+ * Workflow resource class.
+ */
+export class WorkflowResource extends FileResource {
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'workflows');
+
+    this.contentSchemaId = 'workflowSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+
+    this.initialize();
+  }
+
+  // When resource name changes.
+  private async handleNameChange(existingName: string) {
+    await Promise.all([
+      super.updateHandleBars(existingName, this.content.name),
+      super.updateCalculations(existingName, this.content.name),
+    ]);
+    // Finally, write updated content.
+    await this.write();
+  }
+
+  // Update dependant card types.
+  private async updateCardTypes(oldName: string) {
+    const cardTypes = await this.project.cardTypes(ResourcesFrom.localOnly);
+    const op = {
+      name: 'change',
+      target: oldName,
+      to: this.content.name,
+    } as ChangeOperation<string>;
+    for (const cardType of cardTypes) {
+      const object = new CardTypeResource(
+        this.project,
+        resourceName(cardType.name),
+      );
+      if (object.data && (object.data as CardType).workflow === oldName) {
+        await object.update('workflow', op);
+      }
+    }
+  }
+
+  /**
+   * Sets new metadata into the workflow object.
+   * @param newContent metadata content for the workflow.
+   * @throws if 'newContent' is not valid.
+   */
+  public async create(newContent?: Workflow) {
+    if (!newContent) {
+      newContent = DefaultContent.workflow(
+        resourceNameToString(this.resourceName),
+      );
+    } else {
+      await this.validate(newContent);
+    }
+    return super.create(newContent);
+  }
+
+  /**
+   * Returns content data.
+   */
+  public get data(): Workflow {
+    return super.data as Workflow;
+  }
+
+  /**
+   * Deletes file that this object is based on.
+   * If there are card types that depended on this workflow, they are now invalid.
+   */
+  public async delete() {
+    return super.delete();
+  }
+
+  /**
+   * Renames the object and the file.
+   * @param newName New name for the resource.
+   */
+  public async rename(newName: ResourceName) {
+    const existingName = this.content.name;
+    await super.rename(newName);
+    return this.handleNameChange(existingName);
+  }
+
+  /**
+   * Shows metadata of the resource.
+   * @returns workflow metadata.
+   */
+  public async show(): Promise<Workflow> {
+    return super.show() as Promise<Workflow>;
+  }
+
+  /**
+   * Updates workflow resource.
+   * @param key Key to modify
+   * @param op Operation to perform on 'key'
+   * @throws if key is unknown.
+   */
+  public async update<Type>(key: string, op: Operation<Type>) {
+    const nameChange = key === 'name';
+    const existingName = this.content.name;
+
+    await super.update(key, op);
+
+    const content = { ...(this.content as Workflow) };
+
+    if (key === 'name') {
+      content.name = super.handleScalar(op) as string;
+    } else if (key === 'states') {
+      content.states = super.handleArray(
+        op,
+        key,
+        content.states as Type[],
+      ) as WorkflowState[];
+    } else if (key === 'transitions') {
+      content.transitions = super.handleArray(
+        op,
+        key,
+        content.transitions as WorkflowTransition[] as Type[],
+      ) as WorkflowTransition[];
+    } else {
+      throw new Error(`Unknown property '${key}' for Workflow`);
+    }
+
+    await super.postUpdate(content, key, op);
+
+    // Renaming this workflow causes that references to its name must be updated.
+    if (nameChange) {
+      await this.handleNameChange(existingName);
+      await this.updateCardTypes(existingName);
+    }
+  }
+
+  /**
+   * List where workflow is used.
+   * Always returns card key references first, then any resource references and finally calculation references.
+   *
+   * @param cards Optional. Check these cards for usage of this resource. If undefined, will check all cards.
+   * @returns array of card keys, resource names and calculation filenames that refer this resource.
+   */
+  public async usage(cards?: Card[]): Promise<string[]> {
+    const resourceName = resourceNameToString(this.resourceName);
+    const allCards = cards ?? (await super.cards());
+    const cardTypes = await this.project.cardTypes(ResourcesFrom.all);
+    const cardTypeReferences = await Promise.all(
+      cardTypes.map(async (cardType) => {
+        const metadata = await this.project.resource<CardType>(cardType.name);
+        return metadata?.workflow === resourceName ? cardType.name : null;
+      }),
+    );
+
+    const [relevantCards, calculations] = await Promise.all([
+      super.usage(allCards),
+      super.calculations(),
+    ]);
+
+    return [
+      ...relevantCards.sort(sortCards),
+      ...cardTypeReferences.filter((name): name is string => name !== null),
+      ...calculations,
+    ];
+  }
+
+  /**
+   * Validates workflow.
+   * @throws when there are validation errors.
+   */
+  public validate(content?: object): Promise<void> {
+    return super.validate(content);
+  }
+}

package/src/types/queries.ts

@@ -0,0 +1,149 @@
+/**
+    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/>.
+*/
+
+/**
+ * Types for query result
+ */
+
+import type {
+  DataType,
+  WorkflowCategory,
+} from '../interfaces/resource-interfaces.js';
+
+export type LinkDirection = 'inbound' | 'outbound';
+
+export type StatusIndicator = WorkflowCategory | 'error';
+
+export interface CalculationLink {
+  displayName: string;
+  key: string;
+  linkType: string;
+  title: string; // title of the other card
+  linkDescription?: string;
+  direction: LinkDirection;
+  linkSource: 'user' | 'calculated';
+}
+
+export interface Notification {
+  key: string;
+  category: string;
+  title: string;
+  message: string;
+}
+
+export interface PolicyCheckCollection {
+  successes: { category: string; title: string }[];
+  failures: {
+    category: string;
+    title: string;
+    errorMessage: string;
+    fieldName?: string;
+  }[];
+}
+
+export interface DeniedOperationCollection {
+  transition: { transitionName: string; errorMessage: string }[];
+  move: { errorMessage: string }[];
+  delete: { errorMessage: string }[];
+  editField: { fieldName: string; errorMessage: string }[];
+  editContent: { errorMessage: string }[];
+}
+
+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> {
+  results: T[];
+  error: string | null;
+}
+
+/**
+ * Generic types for named queries
+ */
+
+export const queries = ['card', 'onCreation', 'onTransition', 'tree'] as const;
+
+export type QueryName = (typeof queries)[number];
+
+export type QueryMap = {
+  card: CardQueryResult;
+  onCreation: FieldsToUpdateQueryResult;
+  onTransition: FieldsToUpdateQueryResult;
+  tree: TreeQueryResult;
+};
+export type QueryResult<T extends QueryName> = QueryMap[T];
+
+/**
+ * Define all the queries below
+ */
+interface CardQueryResult extends BaseResult {
+  progress?: string;
+  rank: string;
+  title: string;
+  cardType: string;
+  workflowState: string;
+  lastUpdated: string;
+  fields?: CardQueryField[];
+}
+interface FieldsToUpdateQueryResult extends BaseResult {
+  updateFields: UpdateField[];
+}
+interface TreeQueryResult extends BaseResult {
+  progress?: string;
+  rank: string;
+  title: string;
+  cardType: string;
+  statusIndicator?: StatusIndicator;
+  children?: TreeQueryResult[];
+}
+
+export interface UpdateField {
+  card: string;
+  field: string;
+  newValue: string;
+}
+
+interface EnumValue {
+  index?: number;
+  displayValue?: string;
+  value: string;
+}
+
+interface ListValueItem {
+  index?: number;
+  displayValue?: string;
+  value: string;
+}
+
+interface CardQueryField extends BaseResult {
+  visibility: 'always' | 'optional';
+  index: number;
+  fieldDisplayName: string;
+  fieldDescription: string;
+  dataType: DataType;
+  isCalculated: boolean;
+  value: string | number | boolean | null | EnumValue | ListValueItem[];
+  enumValues: EnumDefinition[];
+}
+
+export interface EnumDefinition extends BaseResult {
+  index: number;
+  enumDisplayValue: string;
+  enumDescription: string;
+  enumValue: string;
+}

package/src/utils/card-utils.ts

@@ -0,0 +1,83 @@
+/**
+    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';
+
+import type { Card } from '../interfaces/project-interfaces.js';
+
+// Helper function to find the parent path from a card path
+export const findParentPath = (cardPath: string): string | null => {
+  const pathParts = cardPath.split(sep);
+  const hasChildren = pathParts.lastIndexOf('c');
+
+  if (hasChildren <= 0) return null;
+
+  const parentPathParts = [...pathParts];
+  parentPathParts.splice(hasChildren, 1);
+  return parentPathParts.slice(0, hasChildren).join(sep);
+};
+
+/**
+ * Flattens card tree so that children are shown on same level regardless of nesting level.
+ * @param array card tree
+ * @returns flattened card tree.
+ */
+export const flattenCardArray = (array: Card[]) => {
+  const result: Card[] = [];
+  array.forEach((item) => {
+    const { key, path, children, attachments, metadata } = item;
+    result.push({ key, path, children, attachments, metadata });
+    if (children) {
+      result.push(...flattenCardArray(children));
+    }
+  });
+  return result;
+};
+
+/**
+ * Checks if given card is in some template.
+ * @param card card object to check
+ * @returns true if card exists in a template; false otherwise
+ */
+export const isTemplateCard = (card: Card) => {
+  return (
+    card.path.includes(`${sep}templates${sep}`) ||
+    card.path.includes(`${sep}modules${sep}`)
+  );
+};
+
+/**
+ * Sorts array of cards first using prefix and then using ID.
+ * Prefixes are returned in alphabetical order, and then in numeric order within same prefix.
+ * For example, test_za1, test_aa7 and demo_aaa are sorted to: demo_aaa, test_aa7, test_za1.
+ * @param a First card to be sorted
+ * @param b Second card to be sorted
+ * @returns Cards ordered; first by prefixes, then by ID.
+ */
+export const sortCards = (a: string, b: string) => {
+  const aParts = a.split('_');
+  const bParts = b.split('_');
+  if (aParts[0] !== bParts[0]) {
+    if (aParts[0] > bParts[0]) return 1;
+    if (aParts[0] < bParts[0]) return -1;
+    return 0;
+  }
+  if (a.length > b.length) {
+    return 1;
+  }
+  if (a.length < b.length) {
+    return -1;
+  }
+  if (aParts[1] > bParts[1]) return 1;
+  if (aParts[1] < bParts[1]) return -1;
+  return 0;
+};

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

@@ -0,0 +1,167 @@
+import { INT32_MAX } from './constants.js';
+import { logger } from './log-utils.js';
+
+/**
+    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/>.
+*/
+export type AllowedClingoType = string | number | boolean;
+
+export type NestedBuilder = (builder: ClingoFactBuilder) => ClingoFactBuilder;
+
+type ClingoArgumentInternal =
+  | AllowedClingoType
+  | AllowedClingoType[]
+  | ClingoFactBuilder;
+
+export type ClingoArgument = ClingoArgumentInternal | NestedBuilder;
+
+/**
+ * This function takes care of encoding chars, which might produce issues in clingo
+ * This should be done for user provided values
+ */
+export function encodeClingoValue(value: string) {
+  return value.replace(/[\n\\"]/g, (char) => {
+    if (char === '\n') {
+      return '\\n';
+    }
+    return `\\${char}`;
+  });
+}
+
+export class ClingoFactBuilder {
+  protected predicate: string;
+  private end: string;
+  private arguments: ClingoArgumentInternal[] = [];
+
+  constructor(predicate: string, end: string = '.') {
+    this.predicate = predicate;
+    this.end = end;
+  }
+
+  /**
+   * Adds an argument to the fact
+   * @param arg Argument to add. If null, skipped
+   * @returns this for chaining
+   */
+  addArgument(arg: ClingoArgument | null): ClingoFactBuilder {
+    if (arg === null) {
+      return this;
+    }
+    if (typeof arg === 'function') {
+      const nestedBuilder = new ClingoFactBuilder('', '');
+      this.arguments.push(arg(nestedBuilder));
+    } else {
+      this.arguments.push(arg);
+    }
+    return this;
+  }
+
+  /**
+   * Helper for adding multiple arguments, because it's common
+   * @param args
+   * @returns this for chaining
+   */
+  addArguments(...args: (ClingoArgument | null)[]): ClingoFactBuilder {
+    args.forEach((arg) => this.addArgument(arg));
+    return this;
+  }
+
+  /**
+   * Adds a literal argument, which means that it will not have quotes
+   * @param literal The literal argument to add
+   * @returns this for chaining
+   */
+  addLiteralArgument(literal: string): ClingoFactBuilder {
+    this.arguments.push(new LiteralBuilder(literal));
+    return this;
+  }
+
+  /**
+   * Helper for adding multiple literal arguments, because it's common
+   * @param literal
+   * @returns this for chaining
+   */
+  addLiteralArguments(...literals: string[]): ClingoFactBuilder {
+    literals.forEach((literal) => this.addLiteralArgument(literal));
+    return this;
+  }
+
+  /**
+   * Builds the clingo fact
+   * @returns The clingo fact as a string
+   */
+  build(): string {
+    const encodedArguments = this.arguments
+      .map((arg) =>
+        arg instanceof ClingoFactBuilder
+          ? arg.build()
+          : this.encodeArgument(arg),
+      )
+      .join(', ');
+
+    return `${this.predicate}(${encodedArguments})${this.end}`;
+  }
+
+  // Function to get the raw value of the argument without encoding or quoting
+  private getValue(value: AllowedClingoType | AllowedClingoType[]): string {
+    if (typeof value === 'boolean') {
+      return value ? 'true' : 'false';
+    } else if (Array.isArray(value)) {
+      // Array case, call getValue on each item without quotes
+      return value.map((item) => this.getValue(item)).join(',');
+    } else if (typeof value === 'number') {
+      let floored = Math.floor(value);
+      if (floored !== value) {
+        logger.warn(
+          {
+            value,
+          },
+          'Expected a whole number, when transforming a number value to a clingo equivalent. Decimal part removed.',
+        );
+      }
+
+      const exceedsInt32Max = floored > INT32_MAX;
+      if (exceedsInt32Max || floored < -INT32_MAX) {
+        logger.warn(
+          {
+            value,
+          },
+          `Value exceeds the 32-bit signed integer range. The value is too ${exceedsInt32Max ? 'large' : 'small'} to be represented as a 32-bit integer. Using ${exceedsInt32Max ? INT32_MAX : -INT32_MAX} instead.`,
+        );
+        floored = exceedsInt32Max ? INT32_MAX : -INT32_MAX;
+      }
+      return floored.toString();
+    } else {
+      return value;
+    }
+  }
+
+  // Main encoding function, handling encoding and adding quotes if necessary
+  private encodeArgument(arg: AllowedClingoType | AllowedClingoType[]): string {
+    let processedValue = this.getValue(arg);
+
+    if (typeof arg === 'string') {
+      processedValue = encodeClingoValue(processedValue);
+    }
+
+    if (typeof arg === 'boolean' || typeof arg === 'number') {
+      return processedValue;
+    }
+
+    return `"${processedValue}"`;
+  }
+}
+
+class LiteralBuilder extends ClingoFactBuilder {
+  build() {
+    return this.predicate;
+  }
+}