@cyberismo/data-handler 0.0.15 → 0.0.17

package/src/resources/resource-object.ts

@@ -14,41 +14,43 @@
 
 // node
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { basename, join, sep } from 'node:path';
-
-import { hasCode } from '../utils/error-utils.js';
+import { basename, join } from 'node:path';
 
 import { ArrayHandler } from './array-handler.js';
+import { deleteFile, pathExists } from '../utils/file-utils.js';
+import { getChildLogger } from '../utils/log-utils.js';
+import {
+  readJsonFile,
+  readJsonFileSync,
+  writeJsonFile,
+} from '../utils/json.js';
+import {
+  resourceName,
+  resourceNameToPath,
+  resourceNameToString,
+  type ResourceName,
+} from '../utils/resource-utils.js';
+import { ResourcesFrom } from '../containers/project.js';
+
 import type {
   Card,
-  Resource,
   ResourceFolderType,
 } from '../interfaces/project-interfaces.js';
 import type { Logger } from 'pino';
 import type { Project } from '../containers/project.js';
-import { ResourcesFrom } from '../containers/project/resource-collector.js';
 import type {
   ResourceBaseMetadata,
   UpdateKey,
 } from '../interfaces/resource-interfaces.js';
 import type { Validate } from '../commands/validate.js';
+
 import {
-  resourceName,
-  resourceNameToPath,
-  resourceNameToString,
-  type ResourceName,
-} from '../utils/resource-utils.js';
-import { getChildLogger } from '../utils/log-utils.js';
-import { deleteFile, pathExists } from '../utils/file-utils.js';
-import {
-  readJsonFile,
-  readJsonFileSync,
-  writeJsonFile,
-} from '../utils/json.js';
+  ConfigurationLogger,
+  ConfigurationOperation,
+} from '../utils/configuration-logger.js';
 
 // Possible operations to perform when doing "update"
 export type UpdateOperations = 'add' | 'change' | 'rank' | 'remove';
-//| 'elementTypeChange';
 
 // Base class for update operations.
 type BaseOperation<T> = {
@@ -117,7 +119,7 @@ export abstract class AbstractResource<
   protected abstract delete(): Promise<void>; // delete from disk
   protected abstract read(): Promise<void>; // read content from disk (replaces existing content, if any)
   protected abstract rename(newName: ResourceName): Promise<void>; // change name of the resource and filename; same as update('name', ...)
-  protected abstract show(): Promise<ShowReturnType<T, U>>; // return the content as JSON
+  protected abstract show(): ShowReturnType<T, U>; // return the content as JSON
   protected abstract update<Type, K extends string>(
     updateKey: UpdateKey<K>,
     operation: Operation<Type>,
@@ -136,8 +138,6 @@ export abstract class ResourceObject<
   T extends ResourceBaseMetadata,
   U,
 > extends AbstractResource<T, U> {
-  // TODO: Remove when INTDEV-1048 is implemented, since caching is done at object level
-  private cache: Map<string, JSON>;
   private static validateInstancePromise?: Promise<ValidateInstance>;
 
   protected content: T;
@@ -153,6 +153,12 @@ export abstract class ResourceObject<
    */
   public fileName: string = '';
 
+  /**
+   * Constructs a ResourceObject instance
+   * @param project Project where this resource is
+   * @param resourceName Name for the resource
+   * @param type Type of resource
+   */
   constructor(
     protected project: Project,
     protected resourceName: ResourceName,
@@ -161,12 +167,19 @@ export abstract class ResourceObject<
     super();
     this.moduleResource =
       this.resourceName.prefix !== this.project.projectPrefix;
-    this.cache = this.project.resourceCache;
     this.type = type;
     this.logger = this.getLogger(this.getType);
     this.content = { name: '' } as T; // not found if name is empty
   }
 
+  // Check if resource already exists. First checks the cache, then filesystem.
+  private exists(): boolean {
+    const name = resourceNameToString(this.resourceName);
+    const existsInCache = this.project.resources.exists(name);
+    return existsInCache || pathExists(this.fileName);
+  }
+
+  // Gets Validate command instance.
   private static async getValidate(): Promise<ValidateInstance> {
     // a bit hacky solution to avoid circular dependencies
     if (!this.validateInstancePromise) {
@@ -177,11 +190,14 @@ export abstract class ResourceObject<
     return this.validateInstancePromise;
   }
 
-  private resourceObjectToResource(): Resource {
-    return {
-      name: this.data ? this.data.name : '',
-      path: this.fileName.substring(0, this.fileName.lastIndexOf(sep)),
-    };
+  // Gets handlebar files.
+  private async reportHandlerBarFiles(from: ResourcesFrom = ResourcesFrom.all) {
+    const reports = this.project.resources.reports(from);
+    const handleBarFiles: string[] = [];
+    for (const report of reports) {
+      handleBarFiles.push(...(await report.handleBarFiles()));
+    }
+    return handleBarFiles;
   }
 
   // Type of resource.
@@ -189,19 +205,13 @@ export abstract class ResourceObject<
     return this.type;
   }
 
-  private toCache() {
-    this.cache.set(
-      resourceNameToString(this.resourceName),
-      this.content as unknown as JSON,
-    );
-  }
-
   /**
-   * Checks if resource exists
+   * Checks if resource exists.
+   * This should only throw, if someone creates resources directly; ie. not through the cache
    * @throws if resource does not exist
    */
   protected assertResourceExists() {
-    if (!pathExists(this.fileName)) {
+    if (!this.exists()) {
       const resourceType = `${this.type[0].toUpperCase()}${this.type.slice(1, this.type.length - 1)}`;
       const name = resourceNameToString(this.resourceName);
       throw new Error(
@@ -210,39 +220,30 @@ export abstract class ResourceObject<
     }
   }
 
+  /**
+   * Calculate; empty implementation.
+   */
   protected async calculate() {}
 
-  // Calculations that use this resource.
+  /**
+   * Calculations that use this resource.
+   * @throws if accessing calculations files failed
+   */
   protected async calculations(): Promise<string[]> {
     const references: string[] = [];
     const resourceName = resourceNameToString(this.resourceName);
-    for (const calculation of await this.project.calculations(
-      ResourcesFrom.all,
-    )) {
-      const fileNameWithExtension = calculation.name.endsWith('.lp')
-        ? calculation.name
-        : calculation.name + '.lp';
-      const filename = join(calculation.path, basename(fileNameWithExtension));
-      try {
-        const content = await readFile(filename, 'utf-8');
-        if (content.includes(resourceName)) {
-          references.push(calculation.name);
-        }
-      } catch (error) {
-        // Skip files that don't exist (they may have been renamed or deleted)
-        if (hasCode(error) && error.code === 'ENOENT') {
-          this.logger.warn(`Skipping non-existent file: ${filename}`);
-          continue;
-        }
-        throw new Error(
-          `Failed to process file ${filename}: ${(error as Error).message}`,
-        );
+    for (const calculation of this.project.resources.calculations()) {
+      const content = calculation.contentData();
+      if (content.calculation && content.calculation.includes(resourceName)) {
+        references.push(calculation.data!.name);
       }
     }
     return references;
   }
 
-  // Cards from project.
+  /**
+   * Cards from project.
+   */
   protected cards(): Card[] {
     return [
       ...this.project.cards(undefined),
@@ -264,9 +265,15 @@ export abstract class ResourceObject<
     ] as unknown as JSON;
   }
 
-  // Creates resource.
+  /**
+   * Creates resource.
+   * @param newContent Content for resource.
+   * @throws when resource already exists in the project.
+   */
   protected async create(newContent?: T) {
-    if (pathExists(this.fileName)) {
+    this.validateResourceIdentifier();
+
+    if (this.exists()) {
       throw new Error(
         `Resource '${this.resourceName.identifier}' already exists in the project`,
       );
@@ -279,13 +286,17 @@ export abstract class ResourceObject<
       this.resourceFolder = this.project.paths.resourcePath(
         this.resourceName.type as ResourceFolderType,
       );
+      this.fileName = join(
+        this.resourceFolder,
+        this.resourceName.identifier + '.json',
+      );
     }
 
     const validator = await ResourceObject.getValidate();
     const validName = validator.validResourceName(
       this.resourceType(),
       resourceNameToString(this.resourceName),
-      await this.project.projectPrefixes(),
+      this.project.projectPrefixes(),
     );
 
     let validContent = {} as T;
@@ -300,19 +311,27 @@ export abstract class ResourceObject<
     this.content = validContent;
     await this.write();
 
-    // Notify project & collector
-    this.project.addResource(
-      this.resourceObjectToResource(),
-      this.content as unknown as JSON,
-    );
+    const resourceString = resourceNameToString(this.resourceName);
+    this.project.resources.add(resourceString, this);
+
+    // Log resource creation to migration log
+    await this.logResourceOperation('create');
   }
 
+  /**
+   * Gets a logger instance.
+   * @param loggerName
+   * @returns logger instance
+   */
   protected getLogger(loggerName: string): Logger {
     return getChildLogger({
       module: loggerName,
     });
   }
 
+  /**
+   * Returns type of this resource.
+   */
   protected get getType(): string {
     return this.type;
   }
@@ -323,6 +342,7 @@ export abstract class ResourceObject<
    * @param arrayName Name of the array, for error messages.
    * @param array Array to be updated.
    * @returns Changed array after the operation.
+   * @throws when operation cannot be done.
    */
   protected handleArray<Type>(
     operation: Operation<Type>,
@@ -347,6 +367,7 @@ export abstract class ResourceObject<
    * Updates scalar value. The only accepted operation is 'change'
    * @param operation Operation to perform on scalar.
    * @returns What the scalar should be changed to.
+   * @throws when operation cannot be done
    */
   protected handleScalar<Type>(operation: Operation<Type>): Type {
     if (
@@ -359,7 +380,9 @@ export abstract class ResourceObject<
     return operation.to;
   }
 
-  // Initialize the resource.
+  /**
+   * Initialize the resource.
+   */
   protected initialize() {
     if (this.resourceName.type === '') {
       this.resourceName.type = this.type;
@@ -379,26 +402,77 @@ export abstract class ResourceObject<
         : this.project.paths.resourcePath(this.type);
       this.fileName = resourceNameToPath(this.project, this.resourceName);
     }
-    // Read from cache, if entry exists...
-    if (this.cache.has(resourceNameToString(this.resourceName))) {
-      this.content = this.cache.get(
-        resourceNameToString(this.resourceName),
-      ) as unknown as T;
-      return;
+    // Only load content from disk if resource exists in the cache registry
+    if (
+      this.project.resources.exists(resourceNameToString(this.resourceName))
+    ) {
+      try {
+        this.content = readJsonFileSync(this.fileName);
+      } catch {
+        this.logger.debug(
+          `Initializing resource '${resourceNameToString(this.resourceName)}' failed: failed to read file '${this.fileName}'`,
+        );
+      }
     }
-    //... otherwise read from disk and add to cache
-    try {
-      this.content = readJsonFileSync(this.fileName);
-      this.toCache();
-    } catch {
-      // do nothing, it is possible that file has not been created yet.
-      this.logger.info(
-        `Initializing resource '${resourceNameToString(this.resourceName)}' failed: failed to read file '${this.fileName}'`,
-      );
+  }
+
+  // Log details
+  protected async logResourceOperation<Type>(
+    operationType: 'create' | 'delete' | 'update' | 'rename',
+    op?: Operation<Type>,
+    key?: string,
+  ): Promise<void> {
+    let configOperation: ConfigurationOperation;
+    const target = resourceNameToString(this.resourceName);
+    const parameters: Record<string, unknown> = { type: this.type };
+
+    switch (operationType) {
+      case 'create':
+        configOperation = ConfigurationOperation.RESOURCE_CREATE;
+        break;
+      case 'delete':
+        configOperation = ConfigurationOperation.RESOURCE_DELETE;
+        break;
+      case 'update':
+        configOperation = ConfigurationOperation.RESOURCE_UPDATE;
+        if (op) {
+          parameters.operation = op.name;
+        }
+        if (key) {
+          parameters.key = key;
+        }
+        break;
+      case 'rename':
+        configOperation = ConfigurationOperation.RESOURCE_RENAME;
+        if (op && op.name === 'change') {
+          const changeOp = op as ChangeOperation<string>;
+          parameters.oldName = changeOp.target;
+          parameters.newName = changeOp.to;
+        }
+        break;
+      default:
+        throw new Error(`Unknown operation type: ${operationType}`);
     }
+
+    await ConfigurationLogger.log(
+      this.project.basePath,
+      configOperation,
+      target,
+      {
+        parameters,
+      },
+    );
+
+    this.logger.info(`Configuration: ${configOperation} - ${target}`);
   }
 
-  // Called after inherited class has finished 'update' operation.
+  /**
+   * Called after inherited class has finished 'update' operation.
+   * @param content New content for resource
+   * @param updateKey Which property to change
+   * @param op What kind of operation is performed to updateKey
+   * @throws if validation fails after the update
+   */
   protected async postUpdate<Type, K extends string>(
     content: T,
     updateKey: UpdateKey<K>,
@@ -433,38 +507,30 @@ export abstract class ResourceObject<
 
     this.content = content;
     await this.write();
-  }
 
-  // Update resource; the base class makes some checks only.
-  protected async update<Type, K extends string>(
-    key: UpdateKey<K>,
-    _op: Operation<Type>,
-  ): Promise<void> {
-    const content = this.data;
-    if (!content) {
-      throw new Error(
-        `Resource '${resourceNameToString(this.resourceName)}' does not exist`,
-      );
-    }
-    if (this.moduleResource) {
-      throw new Error(`Cannot update module resources`);
-    }
-    if (key.key === '' || key === undefined) {
-      throw new Error(`Cannot update empty key`);
-    }
+    // Log resource update to migration log
+    await this.logResourceOperation('update', op, updateKey.key);
   }
 
-  // Reads content from file to memory.
+  /**
+   * Reads content from file to memory.
+   */
   protected async read() {
     this.content = await readJsonFile(this.fileName);
   }
 
-  // Renames resource.
+  /**
+   * Renames resource.
+   * @param newName New name for the resource.
+   * @throws if trying to rename module resource, or
+   *         if resource does not exist,
+   *         if trying to rename so that type changes
+   */
   protected async rename(newName: ResourceName) {
     if (this.moduleResource) {
       throw new Error(`Cannot rename module resources`);
     }
-    if (!pathExists(this.fileName)) {
+    if (!this.exists()) {
       throw new Error(
         `Resource '${this.resourceName.identifier}' does not exist`,
       );
@@ -479,25 +545,78 @@ export abstract class ResourceObject<
     validator.validResourceName(
       this.resourceType(),
       resourceNameToString(newName),
-      await this.project.projectPrefixes(),
+      this.project.projectPrefixes(),
     );
     const newFilename = join(
       this.project.paths.resourcePath(newName.type as ResourceFolderType),
       newName.identifier + '.json',
     );
+
+    const oldName = resourceNameToString(this.resourceName);
     await rename(this.fileName, newFilename);
 
-    this.cache.delete(resourceNameToString(this.resourceName));
     this.fileName = newFilename;
     this.content.name = resourceNameToString(newName);
+    const newNameString = this.content.name;
     this.resourceName = newName;
-    this.toCache();
+
+    this.project.resources.rename(oldName, newNameString);
+
+    // Log resource rename to migration log
+    await this.logResourceOperation('rename', {
+      name: 'change',
+      target: oldName,
+      to: newNameString,
+    } as ChangeOperation<string>);
+  }
+
+  /**
+   * Update resource; the base class makes some checks only.
+   * @template type Resource type
+   * @template K Resource key
+   * @throws if resource does not exist, or
+   *         if trying to update module content, or
+   *         if key is empty
+   */
+  protected async update<Type, K extends string>(
+    key: UpdateKey<K>,
+    _op: Operation<Type>,
+  ): Promise<void> {
+    const content = this.data;
+    if (!content) {
+      throw new Error(
+        `Resource '${resourceNameToString(this.resourceName)}' does not exist`,
+      );
+    }
+    if (this.moduleResource) {
+      throw new Error(`Cannot update module resources`);
+    }
+    if (key.key === '' || key === undefined) {
+      throw new Error(`Cannot update empty key`);
+    }
+  }
+
+  /**
+   * Validates resource identifier to prevent filesystem operations with invalid names
+   * todo: To Validate?
+   */
+  protected validateResourceIdentifier() {
+    if (!this.moduleResource && this.resourceName.identifier) {
+      const identifier = this.resourceName.identifier;
+      if (!/^[a-zA-Z0-9._-]+$/.test(identifier)) {
+        throw new Error(
+          `Resource identifier must follow naming rules. Identifier '${identifier}' is invalid`,
+        );
+      }
+    }
   }
 
   /**
    * Update calculation files.
    * @param from Resource name to update
    * @param to New name for resource
+   * @throws if 'from' or 'to' is empty string, or
+   *         if there was error accessing calculation files.
    */
   protected async updateCalculations(from: string, to: string) {
     if (!from.trim() || !to.trim()) {
@@ -506,41 +625,16 @@ export abstract class ResourceObject<
       );
     }
 
-    const calculations = await this.project.calculations(
+    const calculations = this.project.resources.calculations(
       ResourcesFrom.localOnly,
     );
 
     await Promise.all(
       calculations.map(async (calculation) => {
-        if (!calculation.path) {
-          throw new Error(
-            `Calculation file's '${calculation.name}' path is not defined`,
-          );
-        }
-
-        const base = basename(calculation.name);
-        const fileNameWithExtension = base.endsWith('.lp')
-          ? base
-          : base + '.lp';
-        const filename = join(calculation.path, fileNameWithExtension);
-
-        try {
-          const content = await readFile(filename, 'utf-8');
-          const updatedContent = content.replaceAll(from, to);
-          await writeFile(filename, updatedContent);
-        } catch (error) {
-          if (hasCode(error) && error.code === 'ENOENT') {
-            // Skip files that don't exist (they may have been renamed or deleted)
-            this.getLogger(this.getType).warn(
-              `Skipping non-existent file: ${filename}`,
-            );
-            return;
-          }
-          if (error instanceof Error) {
-            throw new Error(
-              `Failed to process file while updating calculation ${filename}: ${error.message}`,
-            );
-          }
+        const content = calculation.contentData();
+        if (content.calculation) {
+          const updatedContent = content.calculation.replaceAll(from, to);
+          await calculation.updateFile('calculation.lp', updatedContent);
         }
       }),
     );
@@ -551,6 +645,7 @@ export abstract class ResourceObject<
    * @param from Resource name to update
    * @param to New name for resource
    * @param handleBarFiles Optional. List of handlebar files. If omitted, affects all handlebar files in the project.
+   * @throws if 'from' or 'to' is empty string
    */
   protected async updateHandleBars(
     from: string,
@@ -564,7 +659,7 @@ export abstract class ResourceObject<
     }
 
     if (!handleBarFiles) {
-      handleBarFiles = await this.project.reportHandlerBarFiles(
+      handleBarFiles = await this.reportHandlerBarFiles(
         ResourcesFrom.localOnly,
       );
     }
@@ -579,10 +674,14 @@ export abstract class ResourceObject<
     );
   }
 
-  // Check if there are references to the resource in the card content.
-  // @note that this needs to be async, since inherited classes need to async operations
+  /**
+   * Check if there are references to the resource in the card content.
+   * @note that this needs to be async, since inherited classes need to async operations
+   * @param cards cards to check
+   * @throws if resource does not exist
+   */
   protected async usage(cards?: Card[]): Promise<string[]> {
-    if (!pathExists(this.fileName)) {
+    if (!this.exists()) {
       throw new Error(
         `Resource '${this.resourceName.identifier}' does not exist in the project`,
       );
@@ -596,17 +695,25 @@ export abstract class ResourceObject<
       .map((card) => card.key);
   }
 
+  /**
+   * Checks if resource name is valid.
+   * @param newName New name for resource.
+   * @returns valid name
+   */
   protected async validName(newName: ResourceName) {
     const validator = await ResourceObject.getValidate();
     const validName = validator.validResourceName(
       this.resourceType(),
       resourceNameToString(newName),
-      await this.project.projectPrefixes(),
+      this.project.projectPrefixes(),
     );
     return validName;
   }
 
-  // Write the content from memory to disk.
+  /**
+   * Write the content from memory to disk.
+   * @throws if trying to write a module resource.
+   */
   protected async write() {
     if (this.moduleResource) {
       throw new Error(`Cannot change module resources`);
@@ -624,15 +731,16 @@ export abstract class ResourceObject<
     // Check if "name" has changed. Changing "name" means renaming the file.
     const nameInContent = resourceName(this.content.name).identifier + '.json';
     const currentFileName = basename(this.fileName);
+    const resourceString = resourceNameToString(this.resourceName);
 
     if (nameInContent !== currentFileName) {
       const newFileName = join(this.resourceFolder, nameInContent);
       await rename(this.fileName, newFileName);
       this.fileName = newFileName;
+      this.resourceName = resourceName(this.content.name);
+      this.project.resources.rename(resourceString, this.content.name);
     }
-
     await writeJsonFile(this.fileName, this.content);
-    this.toCache();
   }
 
   /**
@@ -646,7 +754,9 @@ export abstract class ResourceObject<
 
   /**
    * Deletes the file and removes the resource from project.
-   * @throws if resource is a module resource or does not exist or is used by other resources.
+   * @throws if resource is a module resource, or
+   *         if resource does not exist, or
+   *         if resource is used by other resources.
    */
   public async delete() {
     if (this.moduleResource) {
@@ -657,7 +767,7 @@ export abstract class ResourceObject<
     if (!this.fileName.endsWith('.json')) {
       this.fileName += '.json';
     }
-    if (!pathExists(this.fileName)) {
+    if (!this.exists()) {
       throw new Error(
         `Resource '${this.resourceName.identifier}' does not exist in the project`,
       );
@@ -669,13 +779,17 @@ export abstract class ResourceObject<
       );
     }
     await deleteFile(this.fileName);
-    this.project.removeResource(this.resourceObjectToResource());
+    this.project.resources.remove(resourceNameToString(this.resourceName));
     this.fileName = '';
+
+    // Log resource deletion to migration log
+    await this.logResourceOperation('delete');
   }
 
   /**
    * Validates the content of the resource.
    * @param content Content to be validated.
+   * @throws if content is invalid.
    */
   public async validate(content?: object) {
     const validator = await ResourceObject.getValidate();