@cyberismo/data-handler 0.0.14 → 0.0.16

package/src/commands/transition.ts

@@ -12,59 +12,60 @@
 */
 
 import { ActionGuard } from '../permissions/action-guard.js';
-import type {
-  CardType,
-  Workflow,
-  WorkflowState,
-} from '../interfaces/resource-interfaces.js';
 import { CardMetadataUpdater } from '../card-metadata-updater.js';
 import type { Project } from '../containers/project.js';
+import type { WorkflowState } from '../interfaces/resource-interfaces.js';
 
+/**
+ * Handles transitions.
+ */
 export class Transition {
+  /**
+   * Creates an instance of Transition command.
+   * @param project Project to use.
+   */
   constructor(private project: Project) {}
 
+  // Wrapper to run onTransition query.
+  private async transitionChangesQuery(cardKey: string, transition: string) {
+    if (!cardKey || !transition) return undefined;
+    return this.project.calculationEngine.runQuery('onTransition', 'localApp', {
+      cardKey,
+      transition,
+    });
+  }
+
   /**
    * Transitions a card from its current state to a new state.
    * @param cardKey card key
    * @param transition which transition to do
    */
   public async cardTransition(cardKey: string, transition: WorkflowState) {
-    // Card details
-    const details = await this.project.cardDetailsById(cardKey, {
-      metadata: true,
-    });
-    if (!details || !details.metadata) {
-      throw new Error(`Card ${cardKey} does not exist in the project`);
-    }
+    const card = this.project.findCard(cardKey);
 
-    // Card type
-    const cardType = await this.project.resource<CardType>(
-      details.metadata?.cardType,
-    );
-    if (cardType === undefined) {
-      throw new Error(
-        `Card's card type '${details.metadata?.cardType}' does not exist in the project`,
-      );
+    if (!card.metadata?.cardType) {
+      throw new Error(`Card does not have card type`);
     }
+    // Card type
+    const cardType = this.project.resources
+      .byType(card.metadata?.cardType, 'cardTypes')
+      .show();
 
     // Workflow
-    const workflow = await this.project.resource<Workflow>(cardType.workflow);
-    if (workflow === undefined) {
-      throw new Error(
-        `Card's workflow '${cardType.workflow}' does not exist in the project`,
-      );
-    }
+    const workflow = this.project.resources
+      .byType(cardType.workflow, 'workflows')
+      .show();
 
     // Check that the state transition can be made "from".
     const foundFrom = workflow.transitions.find(
       (item) =>
-        (details.metadata &&
-          item.fromState.includes(details.metadata?.workflowState)) ||
+        (card.metadata &&
+          item.fromState.includes(card.metadata?.workflowState)) ||
         item.fromState.includes('*'),
     );
     if (!foundFrom) {
       throw new Error(
-        `Card's workflow '${cardType.workflow}' does not contain transition from card's current state '${details.metadata?.workflowState}'`,
+        `Card's workflow '${cardType.workflow}' does not contain transition from card's current state '${card.metadata?.workflowState}'`,
       );
     }
 
@@ -80,44 +81,38 @@ export class Transition {
 
     if (
       !(
-        found.fromState.includes(details.metadata?.workflowState) ||
+        (card.metadata?.workflowState &&
+          found.fromState.includes(card.metadata.workflowState)) ||
         found.fromState.includes('*')
       )
     ) {
       throw new Error(
-        `Card's workflow '${cardType.workflow}' does not contain state transition from state '${details.metadata?.workflowState}' for '${transition.name}`,
+        `Card's workflow '${cardType.workflow}' does not contain state transition from state '${card.metadata?.workflowState}' for '${transition.name}`,
       );
     }
 
     const actionGuard = new ActionGuard(this.project.calculationEngine);
     await actionGuard.checkPermission('transition', cardKey, transition.name);
 
-    details.metadata.workflowState = found.toState;
-    details.metadata.lastUpdated = new Date().toISOString();
-    details.metadata.lastTransitioned = new Date().toISOString();
-    return this.project
-      .updateCardMetadata(details, details.metadata)
-      .then(async () => this.transitionChangesQuery(cardKey, transition.name))
-      .then(async (queryResult) => {
-        if (
-          !queryResult ||
-          queryResult.at(0) === undefined ||
-          queryResult.at(0)?.updateFields === undefined
-        ) {
-          return;
-        }
-        const fieldsToUpdate = queryResult.at(0)!.updateFields;
-        return CardMetadataUpdater.apply(this.project, fieldsToUpdate);
-      })
-      .catch((error) => console.error(error));
-  }
-
-  // Wrapper to run onTransition query.
-  private async transitionChangesQuery(cardKey: string, transition: string) {
-    if (!cardKey || !transition) return undefined;
-    return this.project.calculationEngine.runQuery('onTransition', 'localApp', {
-      cardKey,
-      transition,
-    });
+    if (card.metadata) {
+      card.metadata.workflowState = found.toState;
+      card.metadata.lastUpdated = new Date().toISOString();
+      card.metadata.lastTransitioned = new Date().toISOString();
+      return this.project
+        .updateCardMetadata(card, card.metadata)
+        .then(async () => this.transitionChangesQuery(cardKey, transition.name))
+        .then(async (queryResult) => {
+          if (
+            !queryResult ||
+            queryResult.at(0) === undefined ||
+            queryResult.at(0)?.updateFields === undefined
+          ) {
+            return;
+          }
+          const fieldsToUpdate = queryResult.at(0)!.updateFields;
+          return CardMetadataUpdater.apply(this.project, fieldsToUpdate);
+        })
+        .catch((error) => console.error(error));
+    }
   }
 }

package/src/commands/update.ts

@@ -19,20 +19,44 @@ import type {
   RemoveOperation,
   UpdateOperations,
 } from '../resources/resource-object.js';
-import { Project } from '../containers/project.js';
-import { resourceName } from '../utils/resource-utils.js';
+import type { Project } from '../containers/project.js';
+import type { UpdateKey } from '../interfaces/resource-interfaces.js';
 
 /**
  * Class that handles 'update' commands.
  */
 export class Update {
+  /**
+   * Creates an instance of Update command.
+   * @param project Project to use.
+   */
   constructor(private project: Project) {}
 
+  /**
+   * Update single resource property
+   * This is similar to updateValue, but allows the operation to be fully specified
+   * @param name Name of the resource to operate on.
+   * @param updateKey Property to change in resource or in resource content.
+   * @param operation The full operation object
+   * @template Type Type of the target of the operation
+   * @template T Type of operation ('add', 'remove', 'change', 'rank')
+   * @template K Type of the key to change
+   */
+  public async applyResourceOperation<
+    Type,
+    T extends UpdateOperations,
+    K extends string,
+  >(name: string, updateKey: UpdateKey<K>, operation: OperationFor<Type, T>) {
+    const type = this.project.resources.extractType(name);
+    const resource = this.project.resources.byType(name, type);
+    await resource?.update(updateKey, operation);
+  }
+
   /**
    * Updates single resource property.
    * @param name Name of the resource to operate on.
    * @param operation Operation to perform ('add', 'remove', 'change', 'rank')
-   * @param key Property to change in resource JSON
+   * @param key Property to change in resource JSON. If content, content/<property>
    * @param value Value for 'key'
    * @param optionalDetail Additional detail needed for some operations. For example, 'update' needs a new value.
    * @param mappingTable Optional mapping table for workflow state transitions (only used for workflow changes)
@@ -75,26 +99,23 @@ export class Update {
         ? optionalDetail
         : undefined;
     }
+    const splitKey = key.split('/');
+    if (splitKey.length !== 1 && splitKey.length !== 2) {
+      throw new Error(
+        `Invalid key format: ${key}. Use 'property' or 'content/<property>'.`,
+      );
+    }
 
-    await this.applyResourceOperation(name, key, op);
-  }
-
-  /**
-   * Update single resource property
-   * This is similar to updateValue, but allows the operation to be fully specified
-   * @param name Name of the resource to operate on.
-   * @param key Property to change in resource JSON
-   * @param operation The full operation object
-   * @template Type Type of the target of the operation
-   * @template T Type of operation ('add', 'remove', 'change', 'rank')
-   */
-  public async applyResourceOperation<Type, T extends UpdateOperations>(
-    name: string,
-    key: string,
-    operation: OperationFor<Type, T>,
-  ) {
-    const resource = Project.resourceObject(this.project, resourceName(name));
-    await resource?.update(key, operation);
-    this.project.collectLocalResources();
+    if (splitKey.length === 2 && splitKey[0] !== 'content') {
+      throw new Error(
+        `Invalid key format: ${key}. When using 'content', always use as 'content/<property>'.`,
+      );
+    }
+    const [parsedKey, subKey] = splitKey;
+    if (parsedKey === 'content') {
+      await this.applyResourceOperation(name, { key: parsedKey, subKey }, op);
+    } else {
+      await this.applyResourceOperation(name, { key: parsedKey }, op);
+    }
   }
 }

package/src/commands/validate.ts

@@ -12,7 +12,7 @@
 */
 
 // node
-import { type Dirent } from 'node:fs';
+import type { Dirent } from 'node:fs';
 import { basename, dirname, extname, join, parse, resolve } from 'node:path';
 import { readdir } from 'node:fs/promises';
 
@@ -33,13 +33,14 @@ import type {
   CustomField,
   FieldType,
   ReportMetadata,
-  ResourceContent,
+  AnyResourceContent,
   Workflow,
 } from '../interfaces/resource-interfaces.js';
 import { errorFunction } from '../utils/error-utils.js';
 import { isTemplateCard } from '../utils/card-utils.js';
+import { isPredefinedField } from '../utils/constants.js';
 import { pathExists } from '../utils/file-utils.js';
-import { Project } from '../containers/project.js';
+import type { Project } from '../containers/project.js';
 import { readJsonFile } from '../utils/json.js';
 import { type ResourceName, resourceName } from '../utils/resource-utils.js';
 
@@ -51,7 +52,7 @@ const SHORT_TEXT_MAX_LENGTH = 80;
 
 import * as EmailValidator from 'email-validator';
 import { evaluateMacros } from '../macros/index.js';
-const baseDir = import.meta.dirname;
+const baseDir = import.meta.dirname ?? new URL('.', import.meta.url).pathname;
 const subFoldersToValidate = ['.cards', 'cardRoot'];
 
 export interface LengthProvider {
@@ -82,6 +83,9 @@ export class Validate {
   static dotSchemaSchemaId = '/dotSchema';
   static parameterSchemaFile = 'parameterSchema.json';
 
+  /**
+   * Creates an instance of Validate command.
+   */
   constructor() {
     Validate.baseFolder = pathExists(
       join(process.cwd(), '../../schema', 'cardTreeDirectorySchema.json'),
@@ -117,7 +121,7 @@ export class Validate {
   private checkResourceName(
     file: Dirent,
     content:
-      | ResourceContent
+      | AnyResourceContent
       | CustomField
       | DotSchemaContent
       | ProjectSettings
@@ -133,7 +137,7 @@ export class Validate {
       file.name !== Validate.dotSchemaSchemaId &&
       file.name !== Validate.parameterSchemaFile
     ) {
-      const namedContent = content as ResourceContent | ReportMetadata;
+      const namedContent = content as AnyResourceContent | ReportMetadata;
       if (!namedContent.name) {
         errors.push(
           `File '${file.name}' does not contain 'name' property. Cannot validate resource's 'name'.`,
@@ -167,25 +171,7 @@ export class Validate {
     return join(file.parentPath, file.name);
   }
 
-  // Puts resource to a local cache if found and returns the resource.
-  // If value is already cached, returns from cache.
-  private async getAndCacheResource<Type>(
-    project: Project,
-    cachedValues: Map<string, Type>,
-    valueName: string,
-  ): Promise<Type | undefined> {
-    return (
-      cachedValues.get(valueName) ||
-      project.resource<Type>(valueName).then((resource) => {
-        if (!resource) {
-          return undefined;
-        }
-        cachedValues.set(valueName, resource);
-        return resource;
-      })
-    );
-  }
-
+  // Parses validator messages
   private parseValidatorMessage(errorObject: object[]): string {
     let parsedErrorMessage = '';
     // todo: get schema name here?
@@ -236,7 +222,7 @@ export class Validate {
   ): Promise<string[]> {
     const message: string[] = [];
     try {
-      const prefixes = await project.projectPrefixes();
+      const prefixes = project.projectPrefixes();
       const files = await readdir(path, {
         withFileTypes: true,
       });
@@ -395,11 +381,13 @@ export class Validate {
     const errors: string[] = [];
     if (cardType && fieldArray) {
       const validationPromises = fieldArray.map(async (field) => {
-        const fieldType = await this.getAndCacheResource(
-          project,
-          this.validatedFieldTypes,
-          field,
-        );
+        let fieldType;
+        try {
+          fieldType = project.resources.byType(field, 'fieldTypes').show();
+        } catch {
+          fieldType = undefined;
+        }
+
         if (!fieldType) {
           return `Card type '${cardType.name}' has invalid reference to unknown ${nameOfArray} '${field}'`;
         }
@@ -476,7 +464,7 @@ export class Validate {
 
   /**
    * Validates that new identifier of a resource is according to naming convention.
-   * @param identifier: resource identifier
+   * @param identifier Resource identifier
    * returns true if identifier is valid, and false otherwise.
    */
   public static isValidIdentifierName(identifier: string): boolean {
@@ -550,6 +538,7 @@ export class Validate {
       } else {
         const errorMsg: string[] = [];
         const project = projectFn();
+        await project.populateCaches();
 
         // Then, validate that each 'contentSchema' children as well.
         const result = await this.readAndValidateContentFiles(
@@ -561,10 +550,11 @@ export class Validate {
         }
 
         // Finally, validate that each card is correct
-        const cards = await project.cards();
-        cards.push(...(await project.allTemplateCards()));
+        const cards = project.cards();
+        cards.push(...project.allTemplateCards());
 
         const cardIds = new Map<string, number>();
+        const allPrefixes = await project.projectPrefixes();
 
         for (const card of cards) {
           if (cardIds.has(card.key)) {
@@ -574,7 +564,6 @@ export class Validate {
           }
 
           if (card.metadata) {
-            // validate card's workflow
             if (!isTemplateCard(card)) {
               const validWorkflow = await this.validateWorkflowState(
                 project,
@@ -585,10 +574,10 @@ export class Validate {
               }
             }
           }
-
           const validCustomFields = await this.validateCustomFields(
             project,
             card,
+            allPrefixes,
           );
           if (validCustomFields.length !== 0) {
             errorMsg.push(validCustomFields);
@@ -604,7 +593,7 @@ export class Validate {
             await evaluateMacros(card.content, {
               context: 'localApp',
               mode: 'validate',
-              project,
+              project: project,
               cardKey: card.key,
             });
           }
@@ -671,21 +660,20 @@ export class Validate {
    * @param resourceType Type of resource
    * @param name Name of resource
    * @param prefixes currently used project prefixes
+   * @throws when resource is not from given prefixes,
+   *         or when actual resource does not match the type,
+   *         or when identifier name is not valid
    * @returns resource name as valid resource name; throws in error cases.
    */
-  public async validResourceName(
+  public validResourceName(
     resourceType: ResourceTypes,
     name: string,
     prefixes: string[],
-  ): Promise<string> {
+  ): string {
     const resource = resourceName(name);
     resource.type = resource.type ? resource.type : resourceType;
-    // a bit shaky way to ensure that prefix is set; first of the project prefixes should be the actual project prefix.
     if (resource.prefix === '') {
-      resource.prefix = prefixes.length > 0 ? prefixes.at(0) || '' : '';
-      if (resource.prefix === '') {
-        throw new Error(`Project prefix cannot be empty string`);
-      }
+      throw new Error(`Project prefix cannot be empty string`);
     }
     if (!prefixes.includes(resource.prefix)) {
       throw new Error(
@@ -721,11 +709,13 @@ export class Validate {
    * Validates that card's custom fields are according to schema and have correct data in them.
    * @param project currently used Project
    * @param card specific card
-   * @returns string containing all validation errors
+   * @throws when card does not have metadata
+   * @returns validation errors, if any.
    */
   public async validateCustomFields(
     project: Project,
     card: Card,
+    prefixes: string[],
   ): Promise<string> {
     const validationErrors: string[] = [];
 
@@ -735,11 +725,14 @@ export class Validate {
       );
     }
 
-    const cardType = await this.getAndCacheResource(
-      project,
-      this.validatedCardTypes,
-      card.metadata?.cardType,
-    );
+    let cardType;
+    try {
+      cardType = project.resources
+        .byType(card.metadata?.cardType, 'cardTypes')
+        .show();
+    } catch {
+      cardType = undefined;
+    }
 
     if (!cardType) {
       validationErrors.push(
@@ -765,11 +758,19 @@ export class Validate {
     validationErrors.push(...fieldErrors);
 
     for (const field of cardType.customFields) {
-      const found = await project.resourceExists('fieldTypes', field.name);
-      if (!found) {
+      let fieldType;
+      try {
+        fieldType = await project.resources
+          .byType(field.name, 'fieldTypes')
+          .show();
+      } catch {
+        fieldType = undefined;
+      }
+      if (!fieldType) {
         validationErrors.push(
-          `Custom field '${field.name}' from card type '${cardType.name}' not found from project`,
+          `In card '${card.key}' field '${field.name}' is missing from project\n`,
         );
+        continue;
       }
       if (field.isCalculated) {
         if (card.metadata[field.name] !== undefined) {
@@ -787,19 +788,6 @@ export class Validate {
         }
       }
 
-      const fieldType = await this.getAndCacheResource(
-        project,
-        this.validatedFieldTypes,
-        field.name,
-      );
-
-      if (!fieldType) {
-        validationErrors.push(
-          `In card '${card.key}' field '${field.name}' is missing from project\n`,
-        );
-        continue;
-      }
-
       if (!this.validType(card.metadata[field.name], fieldType)) {
         const typeOfValue = typeof card.metadata[field.name];
         let fieldValue = card.metadata[field.name];
@@ -829,14 +817,46 @@ export class Validate {
       }
     }
 
+    // Validate that all metadata keys are either predefined fields or valid field type names
+    for (const key of Object.keys(card.metadata)) {
+      if (
+        (isPredefinedField(key) as boolean) ||
+        key === 'labels' ||
+        key === 'links'
+      ) {
+        continue;
+      }
+      try {
+        this.validResourceName('fieldTypes', key, prefixes);
+      } catch {
+        validationErrors.push(
+          `Card '${card.key}' has invalid metadata key '${key}'`,
+        );
+        continue;
+      }
+      // Check that the card's fieldType exists in the project
+      let fieldType;
+      try {
+        fieldType = await project.resources.byType(key, 'fieldTypes').show();
+      } catch {
+        fieldType = undefined;
+      }
+      if (!fieldType) {
+        validationErrors.push(
+          `Card '${card.key}' has field '${key}' that does not exist in the project`,
+        );
+      }
+    }
+
     return validationErrors.join('\n');
   }
 
   /**
    * Validates the labels of a card
    * @param card card to validate. Card must have metadata.
+   * @returns validation errors, if any.
    */
-  public async validateCardLabels(card: Card): Promise<string> {
+  public validateCardLabels(card: Card): string {
     const validationErrors: string[] = [];
     if (!card.metadata) {
       validationErrors.push(
@@ -868,7 +888,7 @@ export class Validate {
    * Template cards are expected to have empty workflow state.
    * @param project Project object.
    * @param card Card object to validate
-   * @returns string containing all validation errors
+   * @returns validation errors, if any.
    */
   public async validateWorkflowState(
     project: Project,
@@ -882,12 +902,14 @@ export class Validate {
       );
     }
 
-    // Use caches for cardTypes and workflows, to avoid re-reading the same JSON files multiple times.
-    const cardType = await this.getAndCacheResource(
-      project,
-      this.validatedCardTypes,
-      card.metadata?.cardType || '',
-    );
+    let cardType;
+    try {
+      cardType = card.metadata?.cardType
+        ? project.resources.byType(card.metadata?.cardType, 'cardTypes').show()
+        : undefined;
+    } catch {
+      cardType = undefined;
+    }
     if (!cardType) {
       validationErrors.push(
         `Card '${card.key}' has invalid card type '${card.metadata?.cardType}'`,
@@ -901,11 +923,14 @@ export class Validate {
       return validationErrors.join('\n');
     }
 
-    const workflow = await this.getAndCacheResource(
-      project,
-      this.validatedWorkflows,
-      cardType.workflow,
-    );
+    let workflow;
+    try {
+      workflow = project.resources
+        .byType(cardType.workflow, 'workflows')
+        .show();
+    } catch {
+      workflow = undefined;
+    }
 
     if (!workflow) {
       validationErrors.push(
@@ -934,15 +959,16 @@ export class Validate {
 
   /**
    * Validates a single resource.
-   * @param resource Resource to validate
-   * @returns string containing all validation errors
+   * @param resourceName Resource to validate
+   * @param project Project instance to use.
+   * @returns validation errors, if any.
    */
   public async validateResource(
     resourceName: ResourceName,
     project: Project,
   ): Promise<string> {
     try {
-      const resource = Project.resourceObject(project, resourceName);
+      const resource = project.resources.byType(resourceName);
       await resource.validate();
       return '';
     } catch (error) {