@cyberismo/data-handler 0.0.14 → 0.0.16

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 '../containers/project.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
+ * @param 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-fact-builder.ts

@@ -1,17 +1,19 @@
-import { INT32_MAX } from './constants.js';
-import { getChildLogger } 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.
+  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 { INT32_MAX } from './constants.js';
+import { getChildLogger } from './log-utils.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 type AllowedClingoType = string | number | boolean;
 
 export type NestedBuilder = (builder: ClingoFactBuilder) => ClingoFactBuilder;
@@ -26,6 +28,8 @@ 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
+ * @param value Clingo value to encode.
+ * @returns Encoded clingo value.
  */
 export function encodeClingoValue(value: string) {
   return value.replace(/[\n\\"]/g, (char) => {
@@ -36,6 +40,9 @@ export function encodeClingoValue(value: string) {
   });
 }
 
+/**
+ * Clingo fact builder.
+ */
 export class ClingoFactBuilder {
   protected predicate: string;
   private end: string;
@@ -46,6 +53,11 @@ export class ClingoFactBuilder {
     });
   }
 
+  /**
+   * Constructs an instance of ClingoFactBuilder.
+   * @param predicate Predicate
+   * @param end End character; by default a dot ('.')
+   */
   constructor(predicate: string, end: string = '.') {
     this.predicate = predicate;
     this.end = end;
@@ -71,8 +83,8 @@ export class ClingoFactBuilder {
 
   /**
    * Helper for adding multiple arguments, because it's common
-   * @param args
-   * @returns this for chaining
+   * @param args Arguments array
+   * @returns 'this' for chaining
    */
   addArguments(...args: (ClingoArgument | null)[]): ClingoFactBuilder {
     args.forEach((arg) => this.addArgument(arg));
@@ -82,7 +94,7 @@ export class ClingoFactBuilder {
   /**
    * Adds a literal argument, which means that it will not have quotes
    * @param literal The literal argument to add
-   * @returns this for chaining
+   * @returns 'this' for chaining
    */
   addLiteralArgument(literal: string): ClingoFactBuilder {
     this.arguments.push(new LiteralBuilder(literal));
@@ -91,8 +103,8 @@ export class ClingoFactBuilder {
 
   /**
    * Helper for adding multiple literal arguments, because it's common
-   * @param literal
-   * @returns this for chaining
+   * @param literals Array of literals
+   * @returns 'this' for chaining
    */
   addLiteralArguments(...literals: string[]): ClingoFactBuilder {
     literals.forEach((literal) => this.addLiteralArgument(literal));

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)) {
@@ -233,10 +243,9 @@ export const createCardFacts = async (card: Card, project: Project) => {
 
         if (!isPredefinedField(field)) {
           // field is a custom field, find it
-          const fieldType = await project.resource<FieldType>(field);
-          if (!fieldType) {
-            continue;
-          }
+          const fieldType = project.resources
+            .byType(field, 'fieldTypes')
+            .show();
 
           // if it's a list, let's generate multiple values
           if (fieldType.dataType === 'list') {

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';
 

package/src/utils/resource-utils.ts

@@ -88,6 +88,7 @@ export function resourceName(
  * Converts resource name to path.
  * @param project Project
  * @param resourceName Name of the resource (e.g. <prefix>/<type>/<name>)
+ * @param extension Extension of resource. By default '.json'.
  * @returns path to resource metadata file
  */
 export function resourceNameToPath(
@@ -204,7 +205,7 @@ export function resourceNameToString(resourceName: ResourceName): string {
   ) {
     throw new Error(`Not a valid resource name. Prefix is missing.`);
   }
-  return resourceName.prefix && resourceName.type && resourceName.prefix
+  return resourceName.prefix && resourceName.type && resourceName.identifier
     ? `${resourceName.prefix}/${resourceName.type}/${resourceName.identifier}`
     : `${resourceName.identifier}`;
 }

package/dist/containers/project/resource-collector.d.ts

@@ -1,87 +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 { Project } from '../project.js';
-import type { Resource, ResourceFolderType } from '../../interfaces/project-interfaces.js';
-/**
- * Defines where resources are collected from.
- * all - everywhere
- * importOnly - only from imported modules
- * localOnly - only from the project itself; excluding imported modules
- */
-export declare enum ResourcesFrom {
-    all = "all",
-    importedOnly = "imported",
-    localOnly = "local"
-}
-/**
- * This class handles local and modules resources.
- */
-export declare class ResourceCollector {
-    private project;
-    private local;
-    private modules;
-    private modulesCollected;
-    private paths;
-    constructor(project: Project);
-    private addResources;
-    private addModuleResources;
-    private addResourcesFromModules;
-    private joinResources;
-    private localResources;
-    private resourcesSync;
-    /**
-     * Collects all local resources.
-     */
-    collectLocalResources(): void;
-    /**
-     * Collect specific resource from modules.
-     * @param type Type of resource (e.g. 'templates').
-     * @param moduleName Name of the module to collect resources from
-     * @returns array of collected items.
-     */
-    collectResourcesFromModules(type: ResourceFolderType, moduleName?: string): Promise<string[]>;
-    /**
-     * Add a given 'resource' to the local resource arrays.
-     * @param resource Resource to add.
-     */
-    add(resource: Resource): void;
-    /**
-     * Re-collects local resources.
-     */
-    changed(): void;
-    /**
-     * Re-collects imported module resources.
-     */
-    moduleImported(): Promise<void>;
-    /**
-     * Removes a resource from Project.
-     * @param resource Resource to remove.
-     * @returns the modified array.
-     */
-    remove(resource: Resource): Resource[];
-    /**
-     * Checks if resource of 'type' with 'name' exists.
-     * @param type Type of resource (e.g. 'templates').
-     * @param name Name of the resource.
-     * @returns true, if resource exits, false otherwise.
-     */
-    resourceExists(type: ResourceFolderType, name: string): Promise<boolean>;
-    /**
-     * Returns resources of 'type'. Returned resources are either local, or from modules or all of them.
-     * @param type Type of resource (e.g. 'templates').
-     * @param from Defines where resources are collected from.
-     * @returns Array of resources.
-     */
-    resources(type: ResourceFolderType, from?: ResourcesFrom): Promise<Resource[]>;
-}