@cyberismo/data-handler 0.0.14 → 0.0.15

package/src/resources/workflow-resource.ts

@@ -14,6 +14,7 @@
 
 import type {
   CardType,
+  UpdateKey,
   Workflow,
   WorkflowState,
   WorkflowTransition,
@@ -39,14 +40,12 @@ import { resourceName } from './file-resource.js';
 /**
  * Workflow resource class.
  */
-export class WorkflowResource extends FileResource {
+export class WorkflowResource extends FileResource<Workflow> {
   constructor(project: Project, name: ResourceName) {
     super(project, name, 'workflows');
 
     this.contentSchemaId = 'workflowSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
-
-    this.initialize();
   }
 
   // Collect all cards that use this workflow.
@@ -60,11 +59,10 @@ export class WorkflowResource extends FileResource {
       );
       if (
         object.data &&
-        (object.data as CardType).workflow ===
-          resourceNameToString(this.resourceName)
+        object.data.workflow === resourceNameToString(this.resourceName)
       ) {
         // fetch all cards with card type
-        promises.push(this.collectCards({ metadata: true }, cardType.name));
+        promises.push(this.collectCards(cardType.name));
       }
     }
     return (await Promise.all(promises)).flat();
@@ -82,7 +80,7 @@ export class WorkflowResource extends FileResource {
 
   // Handle change of workflow state.
   private async handleStateChange(op: ChangeOperation<WorkflowState>) {
-    const content = structuredClone(this.content) as Workflow;
+    const content = structuredClone(this.content);
     const stateName = this.targetName(op) as string;
     // Check that state can be changed to
     content.transitions = content.transitions.filter(
@@ -107,7 +105,7 @@ 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 = structuredClone(this.content) as Workflow;
+    const content = structuredClone(this.content);
     const stateName = this.targetName(op) as string;
 
     // If there is no replacement value, remove all transitions "to" and "from" this state.
@@ -153,8 +151,8 @@ export class WorkflowResource extends FileResource {
   }
 
   // Potentially updates the changed transition with current properties.
-  private async transitionObject(op: ChangeOperation<WorkflowTransition>) {
-    const content = structuredClone(this.content) as Workflow;
+  private transitionObject(op: ChangeOperation<WorkflowTransition>) {
+    const content = structuredClone(this.content);
     const targetTransitionName = this.targetName(op);
     const currentTransition = content.transitions.filter(
       (item) => item.name === targetTransitionName,
@@ -212,8 +210,13 @@ export class WorkflowResource extends FileResource {
         this.project,
         resourceName(cardType.name),
       );
-      if (object.data && (object.data as CardType).workflow === oldName) {
-        await object.update('workflow', op);
+      if (object.data && object.data.workflow === oldName) {
+        await object.update(
+          {
+            key: 'workflow',
+          },
+          op,
+        );
       }
     }
   }
@@ -234,21 +237,6 @@ export class WorkflowResource extends FileResource {
     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.
@@ -259,25 +247,21 @@ export class WorkflowResource extends FileResource {
     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 updateKey Key to modify
    * @param op Operation to perform on 'key'
    * @throws if key is unknown.
    */
-  public async update<Type>(key: string, op: Operation<Type>) {
+  public async update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    const { key } = updateKey;
     const nameChange = key === 'name';
     const existingName = this.content.name;
 
-    await super.update(key, op);
+    await super.update(updateKey, op);
 
     const content = structuredClone(this.content) as Workflow;
 
@@ -334,7 +318,7 @@ export class WorkflowResource extends FileResource {
       // 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(
+        const toBeRemovedState = this.content.states.find(
           (state) => state.name === op.target,
         );
         removeOp = {
@@ -349,7 +333,7 @@ export class WorkflowResource extends FileResource {
       // 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(
+        const toBeChangedState = this.content.states.find(
           (state) => state.name === op.target,
         );
         changeOp = {
@@ -363,7 +347,7 @@ export class WorkflowResource extends FileResource {
       await this.handleStateChange(changeOp);
     }
 
-    await super.postUpdate(content, key, op);
+    await super.postUpdate(content, updateKey, op);
 
     // Renaming this workflow causes that references to its name must be updated.
     if (nameChange) {
@@ -381,7 +365,7 @@ export class WorkflowResource extends FileResource {
    */
   public async usage(cards?: Card[]): Promise<string[]> {
     const resourceName = resourceNameToString(this.resourceName);
-    const allCards = cards ?? (await super.cards());
+    const allCards = cards ?? super.cards();
     const cardTypes = await this.project.cardTypes(ResourcesFrom.all);
     const cardTypeReferences = await Promise.all(
       cardTypes.map(async (cardType) => {
@@ -401,12 +385,4 @@ export class WorkflowResource extends FileResource {
       ...calculations,
     ];
   }
-
-  /**
-   * Validates workflow.
-   * @throws when there are validation errors.
-   */
-  public validate(content?: object): Promise<void> {
-    return super.validate(content);
-  }
 }

package/src/utils/card-utils.ts

@@ -1,25 +1,161 @@
 /**
-    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.
+import { sep } from 'node:path';
+import { CARD_KEY_SEPARATOR, ROOT } from './constants.js';
 
-    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 {
+  Card,
+  CardWithChildrenCards,
+} from '../interfaces/project-interfaces.js';
+import type { Project } from '../resources/folder-resource.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/>.
-*/
+/**
+ * Builds card hierarchy from flat card list with nested card objects.
+ * This converts the cards hierarchy (where children are string[]) to
+ * CardWithChildrenCards[] (where children are Card[]).
+ * @param flatCards Cards in a flat array.
+ * @returns Cards in hierarchical array with nested card objects
+ */
+export const buildCardHierarchy = (
+  flatCards: Card[],
+): CardWithChildrenCards[] => {
+  const cardMap = new Map(flatCards.map((card) => [card.key, card]));
 
-import { sep } from 'node:path';
+  // Helper to get cards as a map
+  function cards(flatCards: Card[]) {
+    const cardMap = new Map(
+      flatCards.map((card) => [
+        card.key,
+        { ...card, children: [] as string[] },
+      ]),
+    );
+
+    const rootCards: Card[] = [];
+    cardMap.forEach((card) => {
+      if (card.parent && cardMap.has(card.parent)) {
+        const parentCard = cardMap.get(card.parent);
+        if (parentCard) {
+          parentCard.children.push(card.key);
+        }
+      } else {
+        rootCards.push(card);
+      }
+    });
+
+    return rootCards;
+  }
+
+  // Helper to convert from string[] => Card[] children
+  function convert(card: Card): CardWithChildrenCards {
+    const childrenCards = card.children.map((childKey) => {
+      const childCard = cardMap.get(childKey)!;
+      return convert(childCard);
+    });
+
+    return {
+      ...card,
+      childrenCards,
+    };
+  }
+
+  const rootCards = cards(flatCards);
+  return rootCards.map(convert);
+};
+
+/**
+ * Breaks card path to logical parts: cardKey, list of parents, prefix and template
+ * If this is a root card, then parents is undefined.
+ * If this is not a template card, then template is undefined.
+ * @param prefix Project prefix.
+ * @param cardPath Card path to break into parts.
+ * @returns Card parts
+ * @todo: This could also return module name, if card is from a module
+ */
+export const cardPathParts = (
+  prefix: string,
+  cardPath: string,
+): {
+  cardKey: string | undefined;
+  parents: (string | undefined)[];
+  prefix: string;
+  template: string;
+} => {
+  const pathParts = cardPath.split(sep);
+  const cardKey = pathParts.at(pathParts.length - 1);
+  const parents = [];
+  let template = '';
+  let startIndex = -1;
+  let templatesNameIndex = -1;
+
+  const cardRootIndex = pathParts.indexOf('cardRoot');
+  const projectInternalsIndex = pathParts.indexOf('.cards');
 
-import type { Card } from '../interfaces/project-interfaces.js';
+  if (projectInternalsIndex === -1 && cardRootIndex >= 0) {
+    startIndex = projectInternalsIndex;
+  } else if (projectInternalsIndex >= 0 && cardRootIndex === -1) {
+    const templatesIndex = pathParts.indexOf('templates');
+    startIndex = templatesIndex;
+    if (templatesIndex === -1) {
+      throw new Error(
+        `Invalid card path. Template card must have 'templates' in path`,
+      );
+    }
+    const modulesIndex = pathParts.indexOf('modules');
+    if (modulesIndex !== -1) {
+      prefix = pathParts.at(modulesIndex + 1) || '';
+    }
+    templatesNameIndex = templatesIndex + 1;
+    template = `${prefix}/templates/${pathParts.at(templatesNameIndex)}`;
+  } else {
+    throw new Error(`Card must be either project card, or template card`);
+  }
+
+  // Look for parents in the path.
+  let previousWasParent = false;
+  for (let index = startIndex; index <= pathParts.length; index++) {
+    if (previousWasParent) {
+      previousWasParent = false;
+      parents.push(pathParts.at(index - 2));
+    }
+    const cardsSubFolder = pathParts.at(index) === 'c';
+    const ignoreOrNotTemplatesParent =
+      index - 1 !== templatesNameIndex || templatesNameIndex === -1;
+    if (cardsSubFolder && ignoreOrNotTemplatesParent) {
+      previousWasParent = true;
+    }
+  }
 
-// Helper function to find the parent path from a card path
+  return {
+    cardKey: cardKey,
+    parents: parents,
+    prefix: prefix,
+    template: template,
+  };
+};
+
+/**
+ * Find parent path from a card path
+ * @param cardPath Card path to find parent path from.
+ * @returns Parent path
+ */
 export const findParentPath = (cardPath: string): string | null => {
   const pathParts = cardPath.split(sep);
   const hasChildren = pathParts.lastIndexOf('c');
 
-  if (hasChildren <= 0) return null;
+  if (hasChildren <= 0) {
+    return null;
+  }
 
   const parentPathParts = [...pathParts];
   parentPathParts.splice(hasChildren, 1);
@@ -28,21 +164,53 @@ export const findParentPath = (cardPath: string): string | null => {
 
 /**
  * Flattens card tree so that children are shown on same level regardless of nesting level.
- * @param array card tree
- * @returns flattened card tree.
+ * @param array Card tree to flatten
+ * @parent project Project to use
+ * @returns Flattened card tree.
  */
-export const flattenCardArray = (array: Card[]) => {
+export const flattenCardArray = (array: Card[], project: Project) => {
   const result: Card[] = [];
+
   array.forEach((item) => {
     const { key, path, children, attachments, metadata } = item;
-    result.push({ key, path, children, attachments, metadata });
+    const childCardIds = project
+      .cardKeysToCards(children)
+      .map((item) => item.key);
+
+    result.push({
+      key,
+      path,
+      children: [...childCardIds],
+      attachments,
+      metadata,
+    });
     if (children) {
-      result.push(...flattenCardArray(children));
+      result.push(
+        ...flattenCardArray(project.cardKeysToCards(children), project),
+      );
     }
   });
   return result;
 };
 
+/**
+ * Checks if given card is in some module.
+ * @param card Card object to check
+ * @returns true if card exists in a module; false otherwise
+ */
+export const isModuleCard = (card: Card) => {
+  return card.path.includes(`${sep}modules${sep}`);
+};
+
+/**
+ * Checks if given path is from a module.
+ * @param path Path to check
+ * @returns true if path is from a module; false otherwise
+ */
+export const isModulePath = (path: string) => {
+  return path.includes(`${sep}modules${sep}`);
+};
+
 /**
  * Checks if given card is in some template.
  * @param card card object to check
@@ -55,6 +223,37 @@ export const isTemplateCard = (card: Card) => {
   );
 };
 
+/**
+ * Returns module name from card key
+ * @param cardKey Card key
+ * @returns module name
+ * @todo: should be renamed to modulePrefixFromCardKey
+ */
+export const moduleNameFromCardKey = (cardKey: string) => {
+  const parts = cardKey.split(CARD_KEY_SEPARATOR);
+  if (parts.length !== 2) {
+    throw new Error(`Invalid card key: ${cardKey}`);
+  }
+  return parts[0];
+};
+
+/**
+ * Finds parent card key
+ * @param cardPath Card path from which to find parent card
+ * @returns Parent card key
+ */
+export function parentCard(cardPath: string) {
+  const pathParts = cardPath.split(sep);
+  if (
+    pathParts.at(pathParts.length - 2) === 'cardRoot' ||
+    (pathParts.length > 3 && pathParts.at(pathParts.length - 4) === 'templates')
+  ) {
+    return ROOT;
+  } else {
+    return pathParts.at(pathParts.length - 3);
+  }
+}
+
 /**
  * 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.
@@ -64,8 +263,8 @@ export const isTemplateCard = (card: Card) => {
  * @returns Cards ordered; first by prefixes, then by ID.
  */
 export const sortCards = (a: string, b: string) => {
-  const aParts = a.split('_');
-  const bParts = b.split('_');
+  const aParts = a.split(CARD_KEY_SEPARATOR);
+  const bParts = b.split(CARD_KEY_SEPARATOR);
   if (aParts[0] !== bParts[0]) {
     if (aParts[0] > bParts[0]) return 1;
     if (aParts[0] < bParts[0]) return -1;
@@ -81,16 +280,3 @@ 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];
-};

package/src/utils/clingo-facts.ts

@@ -168,6 +168,7 @@ export const createWorkflowFacts = (workflow: Workflow) => {
  */
 export const createCardFacts = async (card: Card, project: Project) => {
   // Small helper to deduce parent path
+  // todo: Should use card-utils
   function parentPath(cardPath: string) {
     const pathParts = cardPath.split(sep);
     if (pathParts.at(pathParts.length - 2) === 'cardRoot') {
@@ -178,6 +179,7 @@ export const createCardFacts = async (card: Card, project: Project) => {
   }
 
   // Helper to deduce template parent path.
+  // todo: Should use card-utils
   function parentPathFromTemplate(card: Card) {
     const cardPath = card.path;
     const pathParts = cardPath.split(sep);
@@ -201,10 +203,18 @@ export const createCardFacts = async (card: Card, project: Project) => {
     }
   }
 
-  const parentsPath = isTemplateCard(card)
-    ? parentPathFromTemplate(card)
-    : parentPath(card.path);
+  // Use card.parent if available, otherwise fall back to path-based calculation
+  const parentsPath =
+    card.parent && card.parent !== 'root'
+      ? card.parent
+      : isTemplateCard(card)
+        ? parentPathFromTemplate(card)
+        : parentPath(card.path);
+
   const builder = new ClingoProgramBuilder().addComment(card.key);
+  if (!isTemplateCard(card)) {
+    builder.addCustomFact('card', (b) => b.addLiteralArgument(card.key));
+  }
 
   if (card.metadata) {
     for (const [field, value] of Object.entries(card.metadata)) {

package/src/utils/clingo-parser.ts

@@ -103,7 +103,7 @@ class ClingoParser {
     childObject: (parentKey: string, name: string, collection: string) => {
       this.childObjectQueue.push({ parentKey, name, collection });
     },
-    field: async (
+    field: (
       key: string,
       fieldName: string,
       fieldValue: string,

package/src/utils/constants.ts

@@ -13,11 +13,17 @@
 
 import type { PredefinedCardMetadata } from '../interfaces/project-interfaces.js';
 
+// Card key separator between project prefix and card ID
+export const CARD_KEY_SEPARATOR = '_';
+
 export const INT32_MAX = 2147483647; // 2^31-1
 
 // Maximum level offset for includeMacro
 export const MAX_LEVEL_OFFSET = 5;
 
+// Root parent name
+export const ROOT = 'root';
+
 /**
  * These are file names that are valid for folder resources.
  * Note that the folders might still contain other files, such as .schema files,

package/src/utils/csv.ts

@@ -10,7 +10,7 @@
     License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { readFile } from 'fs/promises';
+import { readFile } from 'node:fs/promises';
 import { parse } from 'csv-parse/sync';
 import type { CSVRowRaw } from '../interfaces/project-interfaces.js';