@cyberismo/data-handler 0.0.2

package/src/resources/report-resource.ts

@@ -0,0 +1,224 @@
+/**
+  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 { readdir, readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+
+import { copyDir } from '../utils/file-utils.js';
+import type {
+  Card,
+  Operation,
+  Project,
+  ResourceName,
+} from './folder-resource.js';
+import {
+  DefaultContent,
+  FolderResource,
+  resourceNameToString,
+  sortCards,
+} from './folder-resource.js';
+import type {
+  Report,
+  ReportMetadata,
+} from '../interfaces/resource-interfaces.js';
+import type { Schema } from 'jsonschema';
+import { getStaticDirectoryPath } from '@cyberismo/resources';
+
+const CARD_CONTENT_HANDLEBAR_FILE = 'index.adoc.hbs';
+const QUERY_HANDLEBAR_FILE = 'query.lp.hbs';
+const REPORT_SCHEMA_FILE = 'parameterSchema.json';
+
+const staticDirectoryPath = await getStaticDirectoryPath();
+
+/**
+ * Report resource class.
+ */
+export class ReportResource extends FolderResource {
+  private reportSchema: Schema;
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'reports');
+
+    this.contentSchemaId = 'reportSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+
+    this.initialize();
+
+    const schemaPath = join(this.internalFolder, REPORT_SCHEMA_FILE);
+    this.reportSchema = this.readSchemaFile(schemaPath);
+  }
+
+  // Path to content folder.
+  // @todo: create the files' content dynamically.
+  private defaultReportLocation: string = join(
+    staticDirectoryPath,
+    'defaultReport',
+  );
+
+  // When resource name changes.
+  private async handleNameChange(existingName: string) {
+    await Promise.all([
+      super.updateHandleBars(
+        existingName,
+        this.content.name,
+        await this.handleBarFiles(),
+      ),
+      super.updateCalculations(existingName, this.content.name),
+    ]);
+    // Finally, write updated content.
+    await this.write();
+  }
+
+  // Try to read schema file content
+  private readSchemaFile(path: string) {
+    try {
+      const schema = readFileSync(path);
+      return JSON.parse(schema.toString());
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Sets new metadata into the report object.
+   * @param newContent metadata content for the report.
+   * @throws if 'newContent' is not valid.
+   */
+  public async createReport() {
+    const defaultContent = DefaultContent.report(
+      resourceNameToString(this.resourceName),
+    );
+
+    await super.create(defaultContent);
+
+    // Copy report default structure to destination.
+    await copyDir(this.defaultReportLocation, this.internalFolder);
+  }
+
+  /**
+   * Returns resource content.
+   */
+  public get data(): ReportMetadata {
+    return super.data as ReportMetadata;
+  }
+
+  /**
+   * Deletes file and folder that this resource is based on.
+   */
+  public async delete() {
+    return super.delete();
+  }
+
+  /**
+   * Returns list of handlebar filenames that this report has.
+   * @returns list of handlebar filenames that this report has.
+   */
+  public async handleBarFiles() {
+    return (
+      await readdir(this.internalFolder, {
+        withFileTypes: true,
+        recursive: true,
+      })
+    )
+      .filter((dirent) => dirent.isFile() && extname(dirent.name) === '.hbs')
+      .map((item) => join(item.parentPath, item.name));
+  }
+
+  /**
+   * 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 report metadata.
+   */
+  public async show(): Promise<Report> {
+    const reportMetadata = (await super.show()) as ReportMetadata;
+    return {
+      name: resourceNameToString(this.resourceName),
+      metadata: reportMetadata,
+      contentTemplate: (
+        await readFile(join(this.internalFolder, CARD_CONTENT_HANDLEBAR_FILE))
+      ).toString(),
+      queryTemplate: (
+        await readFile(join(this.internalFolder, QUERY_HANDLEBAR_FILE))
+      ).toString(),
+      schema: this.reportSchema,
+    };
+  }
+
+  /**
+   * Updates report 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 ReportMetadata) };
+
+    if (key === 'name') {
+      content.name = super.handleScalar(op) as string;
+    } else if (key === 'displayName') {
+      content.displayName = super.handleScalar(op) as string;
+    } else if (key === 'description') {
+      content.description = super.handleScalar(op) as string;
+    } else if (key === 'category') {
+      content.category = super.handleScalar(op) as string;
+    }
+
+    await super.postUpdate(content, key, op);
+
+    // Renaming this report causes that references to its name must be updated.
+    if (nameChange) {
+      await this.handleNameChange(existingName);
+    }
+  }
+
+  /**
+   * List where this resource is used.
+   * Always returns card key references first, then calculation references.
+   *
+   * @param cards Optional. Check these cards for usage of this resource. If undefined, will check all cards.
+   * @returns array of card keys and calculation filenames that refer this resource.
+   */
+  public async usage(cards?: Card[]): Promise<string[]> {
+    const allCards = cards ?? (await super.cards());
+    const [relevantCards, calculations] = await Promise.all([
+      super.usage(allCards),
+      super.calculations(),
+    ]);
+    return [...relevantCards.sort(sortCards), ...calculations];
+  }
+
+  /**
+   * Validates report.
+   * @throws when there are validation errors.
+   * @param content Content to be validated.
+   * @note If content is not provided, base class validation will use resource's current content.
+   */
+  public async validate(content?: object) {
+    return super.validate(content);
+  }
+}

package/src/resources/resource-object.ts

@@ -0,0 +1,246 @@
+/**
+    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/>.
+*/
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+// node
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { ArrayHandler } from './array-handler.js';
+import type {
+  Card,
+  ResourceFolderType,
+} from '../interfaces/project-interfaces.js';
+import { type Project, ResourcesFrom } from '../containers/project.js';
+import type { ResourceContent } from '../interfaces/resource-interfaces.js';
+import type { ResourceName } from '../utils/resource-utils.js';
+
+// Possible operations to perform when doing "update"
+export type UpdateOperations = 'add' | 'change' | 'rank' | 'remove';
+//| 'elementTypeChange';
+
+// Base class for update operations.
+type BaseOperation<T> = {
+  name: 'add' | 'change' | 'rank' | 'remove';
+  target: T;
+};
+
+// Add item to an array.
+export type AddOperation<T> = BaseOperation<T> & {
+  name: 'add';
+};
+
+// Change item in an array or property in an object or rename a scalar.
+export type ChangeOperation<T> = BaseOperation<T> & {
+  name: 'change';
+  to: T;
+};
+
+// Move item in an array to new position.
+export type RankOperation<T> = BaseOperation<T> & {
+  name: 'rank';
+  newIndex: number;
+};
+
+// Remove item from an array.
+export type RemoveOperation<T> = BaseOperation<T> & {
+  name: 'remove';
+  replacementValue?: T;
+};
+
+export type Operation<T> =
+  | AddOperation<T>
+  | ChangeOperation<T>
+  | RankOperation<T>
+  | RemoveOperation<T>;
+
+/**
+ * Abstract class for resources.
+ */
+export abstract class AbstractResource {
+  protected abstract calculate(): Promise<void>; // update resource specific calculations
+  protected abstract create(content?: ResourceContent): Promise<void>; // create a new with the content (memory)
+  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<ResourceContent>; // return the content as JSON
+  protected abstract update<Type>(
+    key: string,
+    operation: Operation<Type>,
+  ): Promise<void>; // change one key of resource
+  protected abstract usage(cards?: Card[]): Promise<string[]>; // list of card keys or resource names where this resource is used in
+  protected abstract validate(content?: object): Promise<void>; // validate the content
+  protected abstract write(): Promise<void>; // write content to disk
+}
+
+/**
+ * Base class for all resources.
+ */
+export class ResourceObject extends AbstractResource {
+  protected moduleResource: boolean;
+  protected contentSchema: JSON = {} as JSON;
+  protected contentSchemaId: string = '';
+  protected type: ResourceFolderType = '' as ResourceFolderType;
+  protected resourceFolder: string = '';
+
+  constructor(
+    protected project: Project,
+    protected resourceName: ResourceName,
+  ) {
+    super();
+    this.moduleResource =
+      this.resourceName.prefix !== this.project.projectPrefix;
+  }
+
+  protected async calculate() {}
+  protected async create(_content?: ResourceContent) {}
+  protected async delete() {}
+  protected async read() {}
+  protected async rename(_name: ResourceName) {}
+  protected async show(): Promise<ResourceContent> {
+    return {} as ResourceContent;
+  }
+  protected async update<Type>(_key: string, _op: Operation<Type>) {}
+  protected async usage(_cards?: Card[]): Promise<string[]> {
+    return [];
+  }
+  protected async validate(_content?: object) {}
+  protected async write() {}
+
+  /**
+   * Returns .schema content file.
+   * @param schemaId schema id
+   * @returns .schema content.
+   */
+  protected contentSchemaContent(schemaId: string): JSON {
+    return [
+      {
+        id: schemaId,
+        version: 1,
+      },
+    ] as unknown as JSON;
+  }
+
+  /**
+   * Handles operation to an array.
+   * @param operation Operation to perform on array.
+   * @param arrayName Name of the array, for error messages.
+   * @param array Array to be updated.
+   * @returns Changed array after the operation.
+   */
+  protected handleArray<Type>(
+    operation: Operation<Type>,
+    arrayName: string,
+    array: Type[],
+  ): Type[] {
+    const handler = new ArrayHandler<Type>();
+    let result: Type[] = [];
+    try {
+      result = handler.handleArray(operation, array);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(
+          `Cannot perform operation on '${arrayName}'. ${error.message}`,
+        );
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Updates scalar value. The only accepted operation is 'change'
+   * @param operation Operation to perform on scalar.
+   * @returns What the scalar should be changed to.
+   */
+  protected handleScalar<Type>(operation: Operation<Type>): Type {
+    if (
+      operation.name === 'add' ||
+      operation.name === 'rank' ||
+      operation.name === 'remove'
+    ) {
+      throw new Error(`Cannot do operation ${operation.name} on scalar value`);
+    }
+    return (operation as ChangeOperation<Type>).to;
+  }
+
+  /**
+   * Update calculation files.
+   * @param from Resource name to update
+   * @param to New name for resource
+   */
+  protected async updateCalculations(from: string, to: string) {
+    if (!from.trim() || !to.trim()) {
+      throw new Error(
+        'updateCalculations: "from" and "to" parameters must not be empty',
+      );
+    }
+
+    const calculations = await this.project.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 filename = join(calculation.path, basename(calculation.name));
+        try {
+          const content = await readFile(filename, 'utf-8');
+          const updatedContent = content.replaceAll(from, to);
+          await writeFile(filename, updatedContent);
+        } catch (error) {
+          throw new Error(
+            `Failed to process file ${filename}: ${(error as Error).message}`,
+          );
+        }
+      }),
+    );
+  }
+
+  /**
+   * Update references in handlebars.
+   * @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.
+   */
+  protected async updateHandleBars(
+    from: string,
+    to: string,
+    handleBarFiles?: string[],
+  ) {
+    if (!from.trim() || !to.trim()) {
+      throw new Error(
+        'updateHandleBars: "from" and "to" parameters must not be empty',
+      );
+    }
+
+    if (!handleBarFiles) {
+      handleBarFiles = await this.project.reportHandlerBarFiles(
+        ResourcesFrom.localOnly,
+      );
+    }
+
+    // Process all files in parallel.
+    await Promise.all(
+      handleBarFiles.map(async (handleBarFile) => {
+        const content = await readFile(handleBarFile);
+        const updatedContent = content.toString().replaceAll(from, to);
+        await writeFile(handleBarFile, Buffer.from(updatedContent));
+      }),
+    );
+  }
+}

package/src/resources/template-resource.ts

@@ -0,0 +1,210 @@
+/**
+  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 { basename, dirname, join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+import type {
+  Card,
+  Operation,
+  Project,
+  ResourceName,
+} from './folder-resource.js';
+import {
+  DefaultContent,
+  FolderResource,
+  resourceNameToString,
+  sortCards,
+} from './folder-resource.js';
+import type {
+  TemplateConfiguration,
+  TemplateMetadata,
+} from '../interfaces/resource-interfaces.js';
+import { Template } from '../containers/template.js';
+import { writeJsonFile } from '../utils/json.js';
+
+/**
+ * Template resource class.
+ */
+export class TemplateResource extends FolderResource {
+  private cardContainer: Template;
+  private cardsFolder = '';
+  private cardsSchema = super.contentSchemaContent('cardBaseSchema');
+
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'templates');
+
+    this.contentSchemaId = 'templateSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+
+    this.initialize();
+    this.cardsFolder = join(this.internalFolder, 'c');
+
+    // Each template resource contains a template card container (with template cards).
+    this.cardContainer = new Template(this.project, {
+      name: basename(this.fileName),
+      path: dirname(this.fileName),
+    });
+  }
+
+  // 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();
+  }
+
+  /**
+   * Sets new metadata into the template object.
+   * @param newContent metadata content for the template.
+   * @throws if 'newContent' is not valid.
+   */
+  public async create(newContent?: TemplateMetadata) {
+    if (!newContent) {
+      newContent = DefaultContent.template(
+        resourceNameToString(this.resourceName),
+      );
+    } else {
+      await this.validate(newContent);
+    }
+
+    return super.create(newContent);
+  }
+
+  /**
+   * Returns content data.
+   */
+  public get data(): TemplateMetadata {
+    return super.data as TemplateMetadata;
+  }
+
+  /**
+   * Deletes file and folder that this resource is based on.
+   */
+  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 template metadata.
+   */
+  public async show(): Promise<TemplateConfiguration> {
+    const templateMetadata = (await super.show()) as TemplateMetadata;
+    const container = this.templateObject();
+
+    return {
+      metadata: templateMetadata,
+      name: resourceNameToString(this.resourceName),
+      path: this.fileName,
+      numberOfCards: (await container.listCards()).length,
+    };
+  }
+
+  /**
+   * Returns template card container object.
+   * @returns template container object
+   */
+  public templateObject(): Template {
+    return this.cardContainer;
+  }
+
+  /**
+   * Updates template 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 TemplateMetadata) };
+
+    if (key === 'name') {
+      content.name = super.handleScalar(op) as string;
+    } else if (key === 'displayName') {
+      content.displayName = super.handleScalar(op) as string;
+    } else if (key === 'description') {
+      content.description = super.handleScalar(op) as string;
+    } else if (key === 'category') {
+      content.category = super.handleScalar(op) as string;
+    } else {
+      throw new Error(`Unknown property '${key}' for Template`);
+    }
+
+    await super.postUpdate(content, key, op);
+
+    // Renaming this template causes that references to its name must be updated.
+    if (nameChange) {
+      await this.handleNameChange(existingName);
+    }
+  }
+
+  /**
+   * List where template is used.
+   * Always returns card key references first, then calculation references.
+   *
+   * @param cards Optional. Check these cards for usage of this resource. If undefined, will check all cards.
+   * @returns array of card keys, and calculation filenames that refer this resource.
+   */
+  public async usage(cards?: Card[]): Promise<string[]> {
+    const allCards = cards ?? (await super.cards());
+    const [relevantCards, calculations] = await Promise.all([
+      super.usage(allCards),
+      super.calculations(),
+    ]);
+    return [...relevantCards.sort(sortCards), ...calculations];
+  }
+
+  /**
+   * Validates template.
+   * @throws when there are validation errors.
+   * @param content Content to be validated.
+   * @note If content is not provided, base class validation will use resource's current content.
+   */
+  public async validate(content?: object) {
+    return super.validate(content);
+  }
+
+  /**
+   * Create the template's cards folder.
+   */
+  public async write() {
+    await super.write();
+    this.cardsFolder = join(this.internalFolder, 'c');
+
+    // Create folder for cards and put proper content schema file there
+    const schemaContentFile = join(this.cardsFolder, '.schema');
+    await mkdir(this.cardsFolder, { recursive: true });
+    await writeJsonFile(schemaContentFile, this.cardsSchema, {
+      flag: 'wx',
+    });
+  }
+}