@cyberismo/data-handler 0.0.15 → 0.0.17

package/src/resources/template-resource.ts

@@ -14,25 +14,22 @@
 import { 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 { DefaultContent } from './create-defaults.js';
+import { FolderResource } from './folder-resource.js';
+import { resourceNameToString } from '../utils/resource-utils.js';
+import { sortCards } from '../utils/card-utils.js';
+import { Template } from '../containers/template.js';
+import { writeJsonFile } from '../utils/json.js';
+
+import type { Card } from '../interfaces/project-interfaces.js';
+import type { Operation } from './resource-object.js';
+import type { Project } from '../containers/project.js';
+import type { ResourceName } from '../utils/resource-utils.js';
 import type {
   TemplateConfiguration,
   TemplateMetadata,
   UpdateKey,
 } from '../interfaces/resource-interfaces.js';
-import { Template } from '../containers/template.js';
-import { writeJsonFile } from '../utils/json.js';
 
 /**
  * Template resource class.
@@ -51,6 +48,7 @@ export class TemplateResource extends FolderResource<TemplateMetadata, never> {
     this.cardsFolder = join(this.internalFolder, 'c');
 
     // Each template resource contains a template card container (with template cards).
+    // todo: Fix Template constructor not to use Resource, but just this filename with path
     this.cardContainer = new Template(this.project, {
       name: resourceNameToString(this.resourceName),
       path: dirname(this.fileName),
@@ -88,8 +86,11 @@ export class TemplateResource extends FolderResource<TemplateMetadata, never> {
 
   /**
    * Deletes file and folder that this resource is based on.
+   * Also removes template cards from the project's card cache.
    */
   public async delete() {
+    const templateName = resourceNameToString(this.resourceName);
+    this.project.cardsCache.deleteCardsFromTemplate(templateName);
     return super.delete();
   }
 
@@ -107,8 +108,8 @@ export class TemplateResource extends FolderResource<TemplateMetadata, never> {
    * Shows metadata of the resource.
    * @returns template metadata.
    */
-  public async show(): Promise<TemplateConfiguration> {
-    const templateMetadata = await super.show();
+  public show(): TemplateConfiguration {
+    const templateMetadata = super.show();
     const container = this.templateObject();
 
     return {

package/src/resources/workflow-resource.ts

@@ -13,29 +13,24 @@
 */
 
 import type {
-  CardType,
   UpdateKey,
   Workflow,
   WorkflowState,
   WorkflowTransition,
 } from '../interfaces/resource-interfaces.js';
-import { CardTypeResource } from './card-type-resource.js';
+import { DefaultContent } from './create-defaults.js';
+import { FileResource } from './file-resource.js';
+import { resourceNameToString } from '../utils/resource-utils.js';
+import { sortCards } from '../utils/card-utils.js';
+
+import type { Card } from '../interfaces/project-interfaces.js';
 import type {
-  Card,
   ChangeOperation,
   Operation,
-  Project,
   RemoveOperation,
-  ResourceName,
-} from './file-resource.js';
-import {
-  DefaultContent,
-  FileResource,
-  resourceNameToString,
-  sortCards,
-} from './folder-resource.js';
-import { ResourcesFrom } from '../containers/project.js';
-import { resourceName } from './file-resource.js';
+} from './resource-object.js';
+import type { Project } from '../containers/project.js';
+import type { ResourceName } from '../utils/resource-utils.js';
 
 /**
  * Workflow resource class.
@@ -50,19 +45,11 @@ export class WorkflowResource extends FileResource<Workflow> {
 
   // Collect all cards that use this workflow.
   private async collectCardsUsingWorkflow(): Promise<Card[]> {
-    const cardTypes = await this.project.cardTypes(ResourcesFrom.localOnly);
+    const cardTypes = this.project.resources.cardTypes();
     const promises: Promise<Card[]>[] = [];
     for (const cardType of cardTypes) {
-      const object = new CardTypeResource(
-        this.project,
-        resourceName(cardType.name),
-      );
-      if (
-        object.data &&
-        object.data.workflow === resourceNameToString(this.resourceName)
-      ) {
-        // fetch all cards with card type
-        promises.push(this.collectCards(cardType.name));
+      if (cardType.data?.workflow === resourceNameToString(this.resourceName)) {
+        promises.push(this.collectCards(cardType.data.name));
       }
     }
     return (await Promise.all(promises)).flat();
@@ -199,25 +186,19 @@ export class WorkflowResource extends FileResource<Workflow> {
 
   // Update dependant card types.
   private async updateCardTypes(oldName: string) {
-    const cardTypes = await this.project.cardTypes(ResourcesFrom.localOnly);
+    const cardTypes = this.project.resources.cardTypes();
     const op = {
       name: 'change',
       target: oldName,
       to: this.content.name,
     } as ChangeOperation<string>;
     for (const cardType of cardTypes) {
-      const object = new CardTypeResource(
-        this.project,
-        resourceName(cardType.name),
+      await cardType.update(
+        {
+          key: 'workflow',
+        },
+        op,
       );
-      if (object.data && object.data.workflow === oldName) {
-        await object.update(
-          {
-            key: 'workflow',
-          },
-          op,
-        );
-      }
     }
   }
 
@@ -366,13 +347,13 @@ export class WorkflowResource extends FileResource<Workflow> {
   public async usage(cards?: Card[]): Promise<string[]> {
     const resourceName = resourceNameToString(this.resourceName);
     const allCards = cards ?? super.cards();
-    const cardTypes = await this.project.cardTypes(ResourcesFrom.all);
-    const cardTypeReferences = await Promise.all(
-      cardTypes.map(async (cardType) => {
-        const metadata = await this.project.resource<CardType>(cardType.name);
-        return metadata?.workflow === resourceName ? cardType.name : null;
-      }),
-    );
+    const cardTypes = this.project.resources.cardTypes();
+    const cardTypeReferences = [];
+    for (const cardType of cardTypes) {
+      if (cardType.data?.workflow === resourceName) {
+        cardTypeReferences.push(cardType.data.name);
+      }
+    }
 
     const [relevantCards, calculations] = await Promise.all([
       super.usage(allCards),

package/src/utils/card-utils.ts

@@ -18,7 +18,7 @@ import type {
   Card,
   CardWithChildrenCards,
 } from '../interfaces/project-interfaces.js';
-import type { Project } from '../resources/folder-resource.js';
+import type { Project } from '../containers/project.js';
 
 /**
  * Builds card hierarchy from flat card list with nested card objects.
@@ -165,7 +165,7 @@ 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 to flatten
- * @parent project Project to use
+ * @param project Project to use
  * @returns Flattened card tree.
  */
 export const flattenCardArray = (array: Card[], project: Project) => {

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

@@ -243,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/configuration-logger.ts

@@ -0,0 +1,206 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  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 { readFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getChildLogger } from './log-utils.js';
+import { ProjectPaths } from '../containers/project/project-paths.js';
+import { writeFileSafe, pathExists } from './file-utils.js';
+
+/**
+ * Enum for configuration change operation types.
+ */
+export enum ConfigurationOperation {
+  MODULE_ADD = 'module_add',
+  MODULE_REMOVE = 'module_remove',
+  PROJECT_RENAME = 'project_rename',
+  RESOURCE_CREATE = 'resource_create',
+  RESOURCE_DELETE = 'resource_delete',
+  RESOURCE_RENAME = 'resource_rename',
+  RESOURCE_UPDATE = 'resource_update',
+}
+
+/**
+ * Individual log entry representing a single configuration change.
+ * @param timestamp Timestamp when the operation occurred (ISO string)
+ * @param operation Type of operation performed
+ * @param target Target of the operation
+ * @param parameters Additional parameters specific to the operation
+ */
+export interface ConfigurationLogEntry {
+  timestamp: string;
+  operation: ConfigurationOperation;
+  target: string;
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * Options for logging configuration changes.
+ * @param parameters  Additional parameters to store with the operation
+ */
+export interface ConfigurationLogOptions {
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * Logger for tracking configuration changes that affect project structure.
+ */
+export class ConfigurationLogger {
+  /**
+   * Path to the configuration log file.
+   * @param projectPath Path to the project root
+   * @returns Path to the log file
+   */
+  public static logFile(projectPath: string): string {
+    const paths = new ProjectPaths(projectPath);
+    return paths.configurationChangesLog;
+  }
+
+  /**
+   * Clears all log entries.
+   * @param projectPath Path to the project root
+   * @note Use with caution.
+   */
+  public static async clearLog(projectPath: string): Promise<void> {
+    const logFile = ConfigurationLogger.logFile(projectPath);
+    await writeFileSafe(logFile, '', 'utf-8');
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+    logger.info('Configuration log cleared');
+  }
+
+  /**
+   * Create a versioned snapshot of the current migration log.
+   * Renames current migrationLog.jsonl to migrationLog_<version>.jsonl
+   * @param projectPath Path to the project root
+   * @param version Version identifier (e.g., "1.0.0", "v2")
+   * @returns Path to the versioned log file
+   */
+  public static async createVersion(
+    projectPath: string,
+    version: string,
+  ): Promise<string> {
+    const paths = new ProjectPaths(projectPath);
+    const currentLogPath = paths.configurationChangesLog;
+    const versionedLogPath = join(
+      paths.migrationLogFolder,
+      `migrationLog_${version}.jsonl`,
+    );
+
+    // Only create version if current log exists and has content
+    if (!pathExists(currentLogPath)) {
+      throw new Error('No current migration log exists to version');
+    }
+
+    const content = await readFile(currentLogPath, 'utf-8');
+    if (!content.trim()) {
+      throw new Error('Current migration log is empty');
+    }
+
+    // Rename current to versioned
+    await rename(currentLogPath, versionedLogPath);
+
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+    logger.info(
+      `Created migration to version: ${version} at ${versionedLogPath}`,
+    );
+
+    return versionedLogPath;
+  }
+
+  /**
+   * Reads all configuration log entries using JSON Lines format.
+   * @param projectPath Path to the project root
+   * @returns Array of log entries
+   */
+  public static async entries(
+    projectPath: string,
+  ): Promise<ConfigurationLogEntry[]> {
+    const logFile = ConfigurationLogger.logFile(projectPath);
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+
+    try {
+      const content = await readFile(logFile, 'utf-8');
+      const lines = content
+        .trim()
+        .split('\n')
+        .filter((line) => line.trim());
+
+      const entries: ConfigurationLogEntry[] = [];
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line) as ConfigurationLogEntry;
+          if (entry.timestamp && entry.operation && entry.target) {
+            entries.push(entry);
+          }
+        } catch {
+          logger.error(`Invalid configuration line: ${line}`);
+        }
+      }
+
+      return entries;
+    } catch (error) {
+      logger.error({ error }, `Failed to read configuration log`);
+      return [];
+    }
+  }
+
+  /**
+   * Check if a configuration log exists for the given project path.
+   * @param projectPath Path to the project root
+   * @returns True if log file exists
+   */
+  public static hasLog(projectPath: string): boolean {
+    const logPath = new ProjectPaths(projectPath).configurationChangesLog;
+    return pathExists(logPath);
+  }
+
+  /**
+   * Log a configuration change operation.
+   * @note This is designed to be called AFTER the operation succeeds.
+   * @param projectPath Path to the project root
+   * @param operation The type of operation
+   * @param target The target of the operation
+   * @param options Additional options for the log entry
+   */
+  public static async log(
+    projectPath: string,
+    operation: ConfigurationOperation,
+    target: string,
+    options?: ConfigurationLogOptions,
+  ): Promise<void> {
+    const logFile = ConfigurationLogger.logFile(projectPath);
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+
+    try {
+      const entry: ConfigurationLogEntry = {
+        timestamp: new Date().toISOString(),
+        operation,
+        target,
+        parameters: options?.parameters,
+      };
+
+      await writeFileSafe(logFile, JSON.stringify(entry) + '\n', {
+        flag: 'a',
+      });
+
+      logger.debug(`Logged ${operation} operation for target: ${target}`);
+    } catch (error) {
+      logger.error(
+        { error, operation, target },
+        `Configuration logging failed`,
+      );
+    }
+  }
+}

package/src/utils/constants.ts

@@ -42,13 +42,15 @@ export const VALID_FOLDER_RESOURCE_FILES = [
  * These are field names that are non-custom fields that present in metadata
  */
 export const PREDEFINED_FIELDS = [
-  'rank',
   'cardType',
-  'title',
-  'workflowState',
+  'labels',
   'lastUpdated',
   'lastTransitioned',
+  'links',
+  'rank',
   'templateCardKey',
+  'title',
+  'workflowState',
 ] satisfies (keyof PredefinedCardMetadata)[];
 
 /**

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,110 +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"
-}
-declare class ResourceCollection {
-    calculations: Resource[];
-    cardTypes: Resource[];
-    fieldTypes: Resource[];
-    graphModels: Resource[];
-    graphViews: Resource[];
-    linkTypes: Resource[];
-    reports: Resource[];
-    templates: Resource[];
-    workflows: Resource[];
-    /**
-     * Returns resource array of a give type.
-     * @param type Resource array type to return.
-     * @param moduleName Name of a module. If given, returns just resources from that module.
-     * @returns resource array of a give type.
-     */
-    resourceArray(type: ResourceFolderType, moduleName?: string): Resource[];
-}
-/**
- * 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(): void;
-    /**
-     * Getter. Provide access for owner to browse module resources.
-     */
-    get moduleResources(): ResourceCollection;
-    /**
-     * 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[]>;
-}
-export {};