@cyberismo/data-handler 0.0.11 → 0.0.13

package/src/containers/project/calculation-engine.ts

@@ -13,7 +13,7 @@
 
 // node
 import { basename, join, resolve } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 
 import { sanitizeSvgBase64 } from '../../utils/sanitize-svg.js';
 import { instance } from '@viz-js/viz';
@@ -57,6 +57,7 @@ import {
   solve,
   setProgram,
   removeProgram,
+  buildProgram,
 } from '@cyberismo/node-clingo';
 import { generateReportContent } from '../../utils/report.js';
 import { lpFiles, graphvizReport } from '@cyberismo/assets';
@@ -110,6 +111,22 @@ export class CalculationEngine {
     return createCardFacts(card, this.project);
   }
 
+  /**
+   * Exports logic program to a given file
+   * @param destination Destination file path
+   * @param programs Programs or categories to export
+   * @param query Query to export, if not provided, all programs will be exported
+   */
+  public async exportLogicProgram(
+    destination: string,
+    programs: string[],
+    query?: QueryName,
+  ) {
+    let logicProgram = query ? this.queryContent(query) : '';
+    logicProgram += await buildProgram('', programs);
+    await writeFile(destination, logicProgram);
+  }
+
   // // Wrapper to run onCreation query.
   private async creationQuery(cardKeys: string[], context: Context) {
     if (!cardKeys) return undefined;
@@ -449,9 +466,7 @@ export class CalculationEngine {
       case 'templates':
         return createTemplateFacts(resource as TemplateMetadata);
       default:
-        throw new Error(
-          `Resource ${resourceNameToString(resourceName)} does not have a logic program`,
-        );
+        return '';
     }
   }
 
@@ -503,6 +518,13 @@ export class CalculationEngine {
     return this.parseClingoResult(clingoOutput);
   }
 
+  private queryContent(queryName: QueryName, options?: unknown) {
+    const content = lpFiles.queries[queryName];
+    const handlebars = Handlebars.create();
+    const compiled = handlebars.compile(content);
+    return compiled(options || {});
+  }
+
   /**
    * Runs a pre-defined query.
    * @param queryName Name of the query file without extension
@@ -514,13 +536,7 @@ export class CalculationEngine {
     context: Context = 'localApp',
     options?: unknown,
   ): Promise<QueryResult<T>[]> {
-    let content = lpFiles.queries[queryName];
-    const handlebars = Handlebars.create();
-    const compiled = handlebars.compile(content);
-    content = compiled(options || {});
-    if (!content) {
-      throw new Error(`Query file ${queryName} not found`);
-    }
+    const content = this.queryContent(queryName, options);
 
     this.logger.trace({ queryName }, 'Running query');
     const clingoOutput = await this.run(content, context);

package/src/containers/project.ts

@@ -110,23 +110,25 @@ export class Project extends CardContainer {
       this.resourceWatcher = new ContentWatcher(
         ignoreRenameFileChanges,
         this.paths.resourcesFolder,
-        async (fileName: string) => {
-          let resource;
-          try {
-            resource = pathToResourceName(
-              this,
-              join(this.paths.resourcesFolder, fileName),
-            );
-            if (!resource) {
+        (fileName: string) => {
+          void (async () => {
+            let resource;
+            try {
+              resource = pathToResourceName(
+                this,
+                join(this.paths.resourcesFolder, fileName),
+              );
+              if (!resource) {
+                return;
+              }
+            } catch {
+              // it wasn't a resource that changed, so ignore the change
               return;
             }
-          } catch {
-            // it wasn't a resource that changed, so ignore the change
-            return;
-          }
-          const resourceName = `${resource.prefix}/${resource.type}/${resource.identifier}`;
-          await this.replaceCacheValue(resourceName);
-          this.resources.collectLocalResources();
+            const resourceName = `${resource.prefix}/${resource.type}/${resource.identifier}`;
+            await this.replaceCacheValue(resourceName);
+            this.resources.collectLocalResources();
+          })();
         },
       );
     }
@@ -164,6 +166,7 @@ export class Project extends CardContainer {
   /**
    * Add a given 'resource' to the local resource arrays.
    * @param resource Resource to add.
+   * @param data JSON data for the resource.
    */
   public addResource(resource: Resource, data: JSON) {
     this.resources.add(resource);
@@ -193,6 +196,7 @@ export class Project extends CardContainer {
    * Returns path to card's attachment folder.
    * @param cardKey card key
    * @returns path to card's attachment folder.
+   * @throws if card path cannot be found
    */
   public async cardAttachmentFolder(cardKey: string): Promise<string> {
     // Check if it is a template card.
@@ -202,9 +206,10 @@ export class Project extends CardContainer {
     }
 
     const pathToProjectCard = this.pathToCard(cardKey);
-    return pathToProjectCard
-      ? join(this.paths.cardRootFolder, pathToProjectCard, 'a')
-      : '';
+    if (!pathToProjectCard) {
+      throw new Error(`Card '${cardKey}' not found`);
+    }
+    return join(this.paths.cardRootFolder, pathToProjectCard, 'a');
   }
 
   /**
@@ -252,6 +257,7 @@ export class Project extends CardContainer {
    * Returned parts are: prefix, card key, array of parents and template name. Template name is returned only for template cards.
    * @param cardPath path to a card
    * @returns card path logical parts
+   * @throws when called with wrong path, or wrong card owner
    * todo: if prefix would be parameter; this could be static, or util method
    */
   public cardPathParts(cardPath: string) {
@@ -458,7 +464,7 @@ export class Project extends CardContainer {
 
   /**
    * Returns an array of all the graph models in the project.
-   * @param from  Defines where resources are collected from.
+   * @param from Defines where resources are collected from.
    * @returns array of all the graph models in the project.
    */
   public async graphModels(
@@ -469,7 +475,7 @@ export class Project extends CardContainer {
 
   /**
    * Returns an array of all the graph views in the project.
-   * @param from  Defines where resources are collected from.
+   * @param from Defines where resources are collected from.
    * @returns array of all the graph views in the project.
    */
   public async graphViews(
@@ -513,7 +519,7 @@ export class Project extends CardContainer {
 
   /**
    * Adds a module from project.
-   * @param moduleName Name of the module
+   * @param module Name of the module
    */
   public async importModule(module: ModuleSetting) {
     // Add module as a dependency.
@@ -534,6 +540,7 @@ export class Project extends CardContainer {
    * Returns whether card is a template card or not
    * @param cardKey card to check.
    * @todo: This is only used from 'remove'. Could it use the static checker?
+   * @returns true, if card is template card; false otherwise
    */
   public async isTemplateCard(cardKey: string): Promise<boolean> {
     const templateCards = await this.allTemplateCards();
@@ -554,7 +561,7 @@ export class Project extends CardContainer {
   /**
    * Returns an array of cards in the project, in the templates or both.
    * Cards don't have content and nor metadata.
-   * @param includeCardsFrom Where to return cards from (project, templates, or both)
+   * @param cardsFrom Where to return cards from (project, templates, or both)
    * @returns all cards in the project.
    */
   public async listCards(
@@ -603,7 +610,7 @@ export class Project extends CardContainer {
 
   /**
    * Return cardIDs of the cards in the project or from templates, or both.
-   * @param includeCardsFrom Where to return cards from (project, templates, or both)
+   * @param cardsFrom Where to return cards from (project, templates, or both)
    * @returns Array of cardIDs.
    * @note that cardIDs are not sorted.
    */
@@ -626,41 +633,35 @@ export class Project extends CardContainer {
       cardsFrom === CardLocation.templatesOnly
     ) {
       promises.push(
-        this.templates().then((templates) =>
-          Promise.allSettled(
-            templates.map(
-              (template) =>
-                new TemplateResource(this, resourceName(template.name)),
-            ),
-          )
-            .then((results) =>
-              results
-                .filter(
-                  (
-                    result,
-                  ): result is PromiseFulfilledResult<TemplateResource> =>
-                    result.status === 'fulfilled' && result.value !== null,
-                )
-                .map((result) => result.value),
+        (async () => {
+          const templates = await this.templates();
+          const templateResources = templates.map(
+            (template) =>
+              new TemplateResource(this, resourceName(template.name)),
+          );
+          const templateObjectsResults =
+            await Promise.allSettled(templateResources);
+          const templateObjects = templateObjectsResults
+            .filter(
+              (result): result is PromiseFulfilledResult<TemplateResource> =>
+                result.status === 'fulfilled' && result.value !== null,
             )
-            .then((templateObjects) =>
-              Promise.allSettled(
-                templateObjects.map((obj) => obj.templateObject().listCards()),
-              ),
+            .map((result) => result.value);
+
+          const listCardsResults = await Promise.allSettled(
+            templateObjects.map((obj) => obj.templateObject().listCards()),
+          );
+          const templateCardIds = new Set<string>();
+          listCardsResults
+            .filter(
+              (result): result is PromiseFulfilledResult<Card[]> =>
+                result.status === 'fulfilled',
             )
-            .then((results) => {
-              const templateCardIds = new Set<string>();
-              results
-                .filter(
-                  (result): result is PromiseFulfilledResult<Card[]> =>
-                    result.status === 'fulfilled',
-                )
-                .forEach((result) => {
-                  result.value.forEach((card) => templateCardIds.add(card.key));
-                });
-              return templateCardIds;
-            }),
-        ),
+            .forEach((result) => {
+              result.value.forEach((card) => templateCardIds.add(card.key));
+            });
+          return templateCardIds;
+        })(),
       );
     }
     const allCardIdSets = await Promise.all(promises);
@@ -682,6 +683,7 @@ export class Project extends CardContainer {
       return {
         name: moduleConfig.name,
         modules: moduleConfig.modules,
+        hubs: moduleConfig.hubs,
         path: modulePath,
         cardKeyPrefix: moduleConfig.cardKeyPrefix,
         calculations: [
@@ -754,6 +756,7 @@ export class Project extends CardContainer {
   /**
    * Returns a new unique card key with project prefix (e.g. test_x649it4x).
    * Random part of string will be always 8 characters in base-36 (0-9a-z)
+   * @param cardIds map of card ids in use already
    * @returns a new card key string
    * @throws if a unique key could not be created within set number of attempts
    */
@@ -772,12 +775,14 @@ export class Project extends CardContainer {
       return newKey;
     }
 
-    throw 'Could not generate unique card key';
+    throw new Error('Could not generate unique card key');
   }
 
   /**
    * Returns an array of new unique card keys with project prefix (e.g. test_x649it4x).
    * Random part of string will be always 8 characters in base-36 (0-9a-z)
+   * @param keysToCreate How many new cards are to be created.
+   * @param cardIds map of card ids in use already
    * @returns an array of new card key strings
    * @throws if a unique key could not be created within set number of attempts
    */
@@ -809,7 +814,7 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Getter. Returns a class that handles the project's paths.
+   * Returns a class that handles the project's paths.
    */
   public get paths(): ProjectPaths {
     return this.projectPaths;
@@ -828,14 +833,14 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Getter. Returns project name.
+   * Returns project name.
    */
   public get projectName(): string {
     return this.settings.name;
   }
 
   /**
-   * Getter. Returns project prefix.
+   * Returns project prefix.
    */
   public get projectPrefix(): string {
     return this.settings.cardKeyPrefix;
@@ -869,7 +874,7 @@ export class Project extends CardContainer {
       const configurationPrefixes = await Promise.all(configurationPromises);
       prefixes.push(...configurationPrefixes);
     } catch {
-      // do nothing if readdir throws
+      // do nothing if readdir throws // TODO: Log it
     }
 
     return prefixes;
@@ -937,6 +942,9 @@ export class Project extends CardContainer {
     return data;
   }
 
+  /**
+   * Returns resource cache.
+   */
   public get resourceCache(): Map<string, JSON> {
     return this.createdResources;
   }
@@ -1000,6 +1008,7 @@ export class Project extends CardContainer {
       name: this.containerName,
       path: this.basePath,
       prefix: this.projectPrefix,
+      hubs: this.configuration.hubs,
       modules: (await this.modules()).map((item) => item.name),
       numberOfCards: (await this.listCards(CardLocation.projectOnly))[0].cards
         .length,
@@ -1131,6 +1140,7 @@ export class Project extends CardContainer {
   /**
    * Validates that card's data is valid.
    * @param card Card to validate.
+   * @returns validation errors, if any
    */
   public async validateCard(card: Card): Promise<string> {
     const invalidCustomData = await this.validator.validateCustomFields(

package/src/containers/template.ts

@@ -439,7 +439,7 @@ export class Template extends CardContainer {
   public async cardAttachmentFolder(cardKey: string): Promise<string> {
     const pathToCard = await this.cardFolder(cardKey);
     if (!pathToCard) {
-      return '';
+      throw new Error(`Template card '${cardKey}' not found`);
     }
     return join(pathToCard, 'a');
   }

package/src/index.ts

@@ -11,8 +11,9 @@
 */
 
 import {
-  CardsOptions,
   Cmd,
+  CmdKey,
+  CmdValue,
   Commands,
   CommandManager,
   ExportFormats,
@@ -21,6 +22,14 @@ import { Validate } from './commands/validate.js';
 export * from './interfaces/project-interfaces.js';
 import { requestStatus } from './interfaces/request-status-interfaces.js';
 import { UpdateOperations } from './resources/resource-object.js';
+export type {
+  Operation,
+  OperationFor,
+  AddOperation,
+  ChangeOperation,
+  RankOperation,
+  RemoveOperation,
+} from './resources/resource-object.js';
 import { evaluateMacros } from './macros/index.js';
 import {
   isResourceFolderType,
@@ -30,8 +39,9 @@ import {
 import { moduleNameFromCardKey } from './utils/card-utils.js';
 
 export {
-  CardsOptions,
   Cmd,
+  CmdKey,
+  CmdValue,
   CommandManager,
   Commands,
   ExportFormats,
@@ -44,3 +54,27 @@ export {
   Validate,
   evaluateMacros,
 };
+
+// Export command-specific option interfaces
+export type {
+  CommandOptions,
+  AllCommandOptions,
+  AddCommandOptions,
+  CalcCommandOptions,
+  CreateCommandOptions,
+  EditCommandOptions,
+  ExportCommandOptions,
+  FetchCommandOptions,
+  ImportCommandOptions,
+  MoveCommandOptions,
+  RankCommandOptions,
+  RemoveCommandOptions,
+  RenameCommandOptions,
+  ReportCommandOptions,
+  ShowCommandOptions,
+  StartCommandOptions,
+  TransitionCommandOptions,
+  UpdateCommandOptions,
+  UpdateModulesCommandOptions,
+  ValidateCommandOptions,
+} from './interfaces/command-options.js';

package/src/interfaces/command-options.ts

@@ -0,0 +1,144 @@
+/**
+  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 type { Level } from 'pino';
+import type { Context } from './project-interfaces.js';
+import type { CmdKey } from '../command-handler.js';
+
+// Base options shared across multiple commands
+export interface BaseCommandOptions {
+  projectPath?: string;
+  logLevel?: Level;
+}
+
+// Options for commands that need context
+export interface ContextualCommandOptions extends BaseCommandOptions {
+  context?: Context;
+}
+
+// Options for 'add' command
+export interface AddCommandOptions extends BaseCommandOptions {
+  repeat?: number;
+}
+
+// Options for 'calc' command
+export type CalcCommandOptions = ContextualCommandOptions;
+
+// Options for 'create' command
+export interface CreateCommandOptions extends BaseCommandOptions {
+  skipModuleImport?: boolean;
+}
+
+// Options for 'edit' command
+export type EditCommandOptions = BaseCommandOptions;
+
+// Options for the 'export' command
+export interface ExportCommandOptions extends BaseCommandOptions {
+  recursive?: boolean;
+  title?: string;
+  name?: string;
+  version?: string;
+  date?: string;
+  revremark?: string;
+}
+
+// Options for 'fetch' command
+export type FetchCommandOptions = BaseCommandOptions;
+
+// Options for 'import' command
+export type ImportCommandOptions = BaseCommandOptions;
+
+// Options for 'move' command
+export type MoveCommandOptions = BaseCommandOptions;
+
+// Options for 'rank' command
+export type RankCommandOptions = BaseCommandOptions;
+
+// Options for 'remove' command
+export type RemoveCommandOptions = BaseCommandOptions;
+
+// Options for 'rename' command
+export type RenameCommandOptions = BaseCommandOptions;
+
+// Options for 'report' command
+export type ReportCommandOptions = ContextualCommandOptions;
+
+// Options for 'show' command
+export interface ShowCommandOptions extends BaseCommandOptions {
+  details?: boolean;
+  showAll?: boolean;
+  showUse?: boolean;
+}
+
+// Options for 'start' command
+export interface StartCommandOptions extends BaseCommandOptions {
+  forceStart?: boolean;
+  watchResourceChanges?: boolean;
+}
+
+// Options for 'transition' command
+export type TransitionCommandOptions = BaseCommandOptions;
+
+// Options for 'update' command
+export interface UpdateCommandOptions extends BaseCommandOptions {
+  mappingFile?: string;
+}
+
+// Options for 'updateModules' command
+export type UpdateModulesCommandOptions = BaseCommandOptions;
+
+// Options for 'validate' command
+export type ValidateCommandOptions = BaseCommandOptions;
+
+// All possible command options
+export type AllCommandOptions =
+  | AddCommandOptions
+  | CalcCommandOptions
+  | CreateCommandOptions
+  | EditCommandOptions
+  | ExportCommandOptions
+  | FetchCommandOptions
+  | ImportCommandOptions
+  | MoveCommandOptions
+  | RankCommandOptions
+  | RemoveCommandOptions
+  | RenameCommandOptions
+  | ReportCommandOptions
+  | ShowCommandOptions
+  | StartCommandOptions
+  | TransitionCommandOptions
+  | UpdateCommandOptions
+  | UpdateModulesCommandOptions
+  | ValidateCommandOptions;
+
+// Map command keys to their option types
+export type CommandOptions<T extends CmdKey> = {
+  add: AddCommandOptions;
+  calc: CalcCommandOptions;
+  create: CreateCommandOptions;
+  edit: EditCommandOptions;
+  export: ExportCommandOptions;
+  fetch: FetchCommandOptions;
+  import: ImportCommandOptions;
+  move: MoveCommandOptions;
+  rank: RankCommandOptions;
+  remove: RemoveCommandOptions;
+  rename: RenameCommandOptions;
+  report: ReportCommandOptions;
+  show: ShowCommandOptions;
+  start: StartCommandOptions;
+  transition: TransitionCommandOptions;
+  update: UpdateCommandOptions;
+  updateModules: UpdateModulesCommandOptions;
+  validate: ValidateCommandOptions;
+}[T];

package/src/interfaces/folder-content-interfaces.ts

@@ -0,0 +1,69 @@
+/**
+  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 type { Schema } from 'jsonschema';
+
+// All file mappings for lookup (filename -> property name)
+export const ALL_FILE_MAPPINGS = {
+  'index.adoc.hbs': 'contentTemplate',
+  'query.lp.hbs': 'queryTemplate',
+  'parameterSchema.json': 'schema',
+  'model.lp': 'model',
+  'view.lp.hbs': 'viewTemplate',
+} as const;
+
+// Reverse mappings from property names to filenames
+export const REVERSE_FILE_MAPPINGS = {
+  contentTemplate: 'index.adoc.hbs',
+  queryTemplate: 'query.lp.hbs',
+  schema: 'parameterSchema.json',
+  model: 'model.lp',
+  viewTemplate: 'view.lp.hbs',
+} as const;
+
+// Content interface for Graph Model resources
+export interface GraphModelContent {
+  model?: string;
+}
+
+// Content interface for Graph View resources
+export interface GraphViewContent {
+  viewTemplate?: string;
+}
+
+// Content interface for Report resources
+export interface ReportContent {
+  contentTemplate: string;
+  queryTemplate: string;
+  schema?: Schema;
+}
+
+/**
+ * Get filename with property name
+ * @param propertyName Property name.
+ * @returns filename that matches property name
+ */
+export function filename(propertyName: string): string | undefined {
+  return REVERSE_FILE_MAPPINGS[
+    propertyName as keyof typeof REVERSE_FILE_MAPPINGS
+  ];
+}
+
+/**
+ * Get property name for a filename
+ * @param filename Filename.
+ * @returns property name that matches filename
+ */
+export function propertyName(filename: string): string | undefined {
+  return ALL_FILE_MAPPINGS[filename as keyof typeof ALL_FILE_MAPPINGS];
+}