@principal-ai/principal-view-core 0.5.6

package/dist/utils/YamlParser.d.ts

@@ -0,0 +1,36 @@
+/**
+ * YAML parsing utility for loading configuration files
+ *
+ * Provides error handling and validation for YAML configuration files.
+ * Supports both .yaml and .yml file extensions.
+ */
+import { PathBasedGraphConfiguration } from '../types/path-based-config';
+export interface YamlParseResult {
+    success: boolean;
+    data?: PathBasedGraphConfiguration;
+    error?: string;
+}
+/**
+ * Parse YAML content into a configuration object
+ *
+ * @param content - Raw YAML string content
+ * @param filename - Optional filename for error messages
+ * @returns Parse result with configuration or error
+ */
+export declare function parseYaml(content: string, filename?: string): YamlParseResult;
+/**
+ * Check if a filename has a valid YAML extension
+ *
+ * @param filename - Filename to check
+ * @returns True if filename ends with .yaml or .yml
+ */
+export declare function isYamlFile(filename: string): boolean;
+/**
+ * Extract configuration name from filename
+ * Removes the .yaml or .yml extension
+ *
+ * @param filename - Filename to process
+ * @returns Configuration name without extension
+ */
+export declare function getConfigNameFromFilename(filename: string): string;
+//# sourceMappingURL=YamlParser.d.ts.map

package/dist/utils/YamlParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"YamlParser.d.ts","sourceRoot":"","sources":["../../src/utils/YamlParser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,2BAA2B,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,CA8B7E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/utils/YamlParser.js

@@ -0,0 +1,63 @@
+/**
+ * YAML parsing utility for loading configuration files
+ *
+ * Provides error handling and validation for YAML configuration files.
+ * Supports both .yaml and .yml file extensions.
+ */
+import * as yaml from 'js-yaml';
+/**
+ * Parse YAML content into a configuration object
+ *
+ * @param content - Raw YAML string content
+ * @param filename - Optional filename for error messages
+ * @returns Parse result with configuration or error
+ */
+export function parseYaml(content, filename) {
+    try {
+        const data = yaml.load(content);
+        if (!data) {
+            return {
+                success: false,
+                error: `Empty YAML file${filename ? `: ${filename}` : ''}`,
+            };
+        }
+        // Basic validation - ensure it has the required structure
+        if (!data.metadata || !data.nodeTypes || !data.edgeTypes) {
+            return {
+                success: false,
+                error: `Invalid configuration structure${filename ? ` in ${filename}` : ''}: missing required fields (metadata, nodeTypes, or edgeTypes)`,
+            };
+        }
+        return {
+            success: true,
+            data,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: `YAML parse error${filename ? ` in ${filename}` : ''}: ${errorMessage}`,
+        };
+    }
+}
+/**
+ * Check if a filename has a valid YAML extension
+ *
+ * @param filename - Filename to check
+ * @returns True if filename ends with .yaml or .yml
+ */
+export function isYamlFile(filename) {
+    return filename.endsWith('.yaml') || filename.endsWith('.yml');
+}
+/**
+ * Extract configuration name from filename
+ * Removes the .yaml or .yml extension
+ *
+ * @param filename - Filename to process
+ * @returns Configuration name without extension
+ */
+export function getConfigNameFromFilename(filename) {
+    return filename.replace(/\.(yaml|yml)$/, '');
+}
+//# sourceMappingURL=YamlParser.js.map

package/dist/utils/YamlParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"YamlParser.js","sourceRoot":"","sources":["../../src/utils/YamlParser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAShC;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,QAAiB;IAC1D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAgC,CAAC;QAE/D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,kBAAkB,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;aAC3D,CAAC;QACJ,CAAC;QAED,0DAA0D;QAC1D,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACzD,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,kCAAkC,QAAQ,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,+DAA+D;aAC1I,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI;SACL,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,mBAAmB,QAAQ,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,YAAY,EAAE;SAC/E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAgB;IACxD,OAAO,QAAQ,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@principal-ai/principal-view-core",
+  "version": "0.5.6",
+  "description": "Core logic and types for graph-based principal view framework",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "scripts": {
+    "build": "bun run build:clean && bun run build:ts",
+    "build:clean": "rm -rf dist",
+    "build:ts": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "zod": "^3.22.0",
+    "date-fns": "^3.0.0",
+    "@principal-ai/repository-abstraction": "^0.2.5",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "jest": "^30.1.3",
+    "typescript": "^5.0.4"
+  },
+  "keywords": [
+    "validation",
+    "graph",
+    "visualization",
+    "testing",
+    "event-driven"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/ConfigurationLoader.test.ts

@@ -0,0 +1,490 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { ConfigurationLoader } from './ConfigurationLoader';
+import type { ConfigurationFile, ConfigurationLoadResult } from './ConfigurationLoader';
+import { InMemoryFileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { PathBasedGraphConfiguration } from './types/path-based-config';
+
+describe('ConfigurationLoader', () => {
+  let fsAdapter: InMemoryFileSystemAdapter;
+  let loader: ConfigurationLoader;
+
+  const validConfig: PathBasedGraphConfiguration = {
+    metadata: {
+      name: 'Test Config',
+      version: '1.0.0',
+      description: 'A test configuration',
+    },
+    nodeTypes: {
+      service: {
+        shape: 'rectangle',
+        color: '#4A90E2',
+        dataSchema: {
+          name: { type: 'string', required: true },
+        },
+      },
+    },
+    edgeTypes: {
+      call: {
+        style: 'solid',
+        color: '#999',
+      },
+    },
+    allowedConnections: [
+      {
+        from: 'service',
+        to: 'service',
+        via: 'call',
+      },
+    ],
+  };
+
+  const architectureConfig: PathBasedGraphConfiguration = {
+    metadata: {
+      name: 'Architecture',
+      version: '1.0.0',
+    },
+    nodeTypes: {
+      component: {
+        shape: 'hexagon',
+        color: '#FF6B6B',
+        dataSchema: {
+          name: { type: 'string', required: true },
+        },
+        sources: ['src/**/*.ts'],
+      },
+    },
+    edgeTypes: {
+      dependency: {
+        style: 'dashed',
+        color: '#888',
+      },
+    },
+    allowedConnections: [
+      {
+        from: 'component',
+        to: 'component',
+        via: 'dependency',
+      },
+    ],
+  };
+
+  beforeEach(() => {
+    fsAdapter = new InMemoryFileSystemAdapter();
+    loader = new ConfigurationLoader(fsAdapter);
+  });
+
+  describe('hasConfigDirectory', () => {
+    test('returns true when .vgc directory exists', () => {
+      fsAdapter.createDir('/project/.vgc');
+
+      expect(loader.hasConfigDirectory('/project')).toBe(true);
+    });
+
+    test('returns false when .vgc directory does not exist', () => {
+      expect(loader.hasConfigDirectory('/project')).toBe(false);
+    });
+
+    test('returns false when .vgc exists but is not a directory', () => {
+      fsAdapter.writeFile('/project/.vgc', 'not a directory');
+
+      expect(loader.hasConfigDirectory('/project')).toBe(false);
+    });
+  });
+
+  describe('listConfigurations', () => {
+    test('returns empty array when .vgc does not exist', () => {
+      const configs = loader.listConfigurations('/project');
+
+      expect(configs).toEqual([]);
+    });
+
+    test('returns list of configuration names', () => {
+      fsAdapter.createDir('/project/.vgc');
+      fsAdapter.writeFile('/project/.vgc/architecture.yaml', JSON.stringify(validConfig));
+      fsAdapter.writeFile('/project/.vgc/data-flow.yaml', JSON.stringify(validConfig));
+      fsAdapter.writeFile('/project/.vgc/deployment.yml', JSON.stringify(validConfig));
+
+      const configs = loader.listConfigurations('/project');
+
+      expect(configs).toEqual(['architecture', 'data-flow', 'deployment']);
+    });
+
+    test('filters out non-YAML files', () => {
+      fsAdapter.createDir('/project/.vgc');
+      fsAdapter.writeFile('/project/.vgc/config1.yaml', JSON.stringify(validConfig));
+      fsAdapter.writeFile('/project/.vgc/README.md', '# README');
+      fsAdapter.writeFile('/project/.vgc/config.json', '{}');
+
+      const configs = loader.listConfigurations('/project');
+
+      expect(configs).toEqual(['config1']);
+    });
+
+    test('returns sorted configuration names', () => {
+      fsAdapter.createDir('/project/.vgc');
+      fsAdapter.writeFile('/project/.vgc/zebra.yaml', JSON.stringify(validConfig));
+      fsAdapter.writeFile('/project/.vgc/alpha.yaml', JSON.stringify(validConfig));
+      fsAdapter.writeFile('/project/.vgc/middle.yaml', JSON.stringify(validConfig));
+
+      const configs = loader.listConfigurations('/project');
+
+      expect(configs).toEqual(['alpha', 'middle', 'zebra']);
+    });
+  });
+
+  describe('loadByName', () => {
+    beforeEach(() => {
+      fsAdapter.createDir('/project/.vgc');
+    });
+
+    test('loads configuration by name with .yaml extension', () => {
+      const yamlContent = `
+metadata:
+  name: Test Config
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    color: '#4A90E2'
+    dataSchema:
+      name:
+        type: string
+        required: true
+edgeTypes:
+  call:
+    style: solid
+    color: '#999'
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+      fsAdapter.writeFile('/project/.vgc/simple.yaml', yamlContent);
+
+      const result = loader.loadByName('simple', '/project');
+
+      expect(result).not.toBeNull();
+      expect(result?.name).toBe('simple');
+      expect(result?.config.metadata.name).toBe('Test Config');
+    });
+
+    test('loads configuration by name with .yml extension', () => {
+      const yamlContent = `
+metadata:
+  name: Alternative Config
+  version: 2.0.0
+nodeTypes:
+  component:
+    shape: hexagon
+    color: '#FF6B6B'
+    dataSchema:
+      id:
+        type: string
+        required: true
+edgeTypes:
+  link:
+    style: dashed
+    color: '#888'
+allowedConnections:
+  - from: component
+    to: component
+    via: link
+`;
+      fsAdapter.writeFile('/project/.vgc/alt.yml', yamlContent);
+
+      const result = loader.loadByName('alt', '/project');
+
+      expect(result).not.toBeNull();
+      expect(result?.name).toBe('alt');
+      expect(result?.config.metadata.name).toBe('Alternative Config');
+    });
+
+    test('returns null when configuration does not exist', () => {
+      const result = loader.loadByName('nonexistent', '/project');
+
+      expect(result).toBeNull();
+    });
+
+    test('returns null when .vgc directory does not exist', () => {
+      const result = loader.loadByName('any', '/no-project');
+
+      expect(result).toBeNull();
+    });
+
+    test('returns null when YAML is invalid', () => {
+      fsAdapter.writeFile('/project/.vgc/invalid.yaml', 'invalid: yaml: content:');
+
+      const result = loader.loadByName('invalid', '/project');
+
+      expect(result).toBeNull();
+    });
+
+    test('returns null when configuration structure is invalid', () => {
+      const yamlContent = `
+metadata:
+  name: Incomplete
+nodeTypes: {}
+# Missing edgeTypes and allowedConnections
+`;
+      fsAdapter.writeFile('/project/.vgc/incomplete.yaml', yamlContent);
+
+      const result = loader.loadByName('incomplete', '/project');
+
+      expect(result).toBeNull();
+    });
+
+    test('prefers .yaml over .yml when both exist', () => {
+      const yamlContent = `
+metadata:
+  name: YAML Version
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    dataSchema:
+      name:
+        type: string
+edgeTypes:
+  call:
+    style: solid
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+      const ymlContent = `
+metadata:
+  name: YML Version
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    dataSchema:
+      name:
+        type: string
+edgeTypes:
+  call:
+    style: solid
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+      fsAdapter.writeFile('/project/.vgc/both.yaml', yamlContent);
+      fsAdapter.writeFile('/project/.vgc/both.yml', ymlContent);
+
+      const result = loader.loadByName('both', '/project');
+
+      expect(result).not.toBeNull();
+      expect(result?.config.metadata.name).toBe('YAML Version');
+    });
+  });
+
+  describe('loadAll', () => {
+    test('returns error when .vgc directory does not exist', () => {
+      const result = loader.loadAll('/project');
+
+      expect(result.configs).toEqual([]);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].file).toBe('.vgc');
+      expect(result.errors[0].error).toContain('not found');
+    });
+
+    test('loads all valid configurations', () => {
+      fsAdapter.createDir('/project/.vgc');
+
+      const config1 = `
+metadata:
+  name: Config 1
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    dataSchema:
+      name:
+        type: string
+edgeTypes:
+  call:
+    style: solid
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+      const config2 = `
+metadata:
+  name: Config 2
+  version: 2.0.0
+nodeTypes:
+  component:
+    shape: hexagon
+    dataSchema:
+      id:
+        type: string
+edgeTypes:
+  link:
+    style: dashed
+allowedConnections:
+  - from: component
+    to: component
+    via: link
+`;
+
+      fsAdapter.writeFile('/project/.vgc/first.yaml', config1);
+      fsAdapter.writeFile('/project/.vgc/second.yml', config2);
+
+      const result = loader.loadAll('/project');
+
+      expect(result.configs).toHaveLength(2);
+      expect(result.errors).toEqual([]);
+      expect(result.configs[0].name).toBe('first');
+      expect(result.configs[1].name).toBe('second');
+    });
+
+    test('skips non-YAML files', () => {
+      fsAdapter.createDir('/project/.vgc');
+
+      const validYaml = `
+metadata:
+  name: Valid
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    dataSchema:
+      name:
+        type: string
+edgeTypes:
+  call:
+    style: solid
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+
+      fsAdapter.writeFile('/project/.vgc/valid.yaml', validYaml);
+      fsAdapter.writeFile('/project/.vgc/README.md', '# README');
+      fsAdapter.writeFile('/project/.vgc/config.json', '{}');
+
+      const result = loader.loadAll('/project');
+
+      expect(result.configs).toHaveLength(1);
+      expect(result.configs[0].name).toBe('valid');
+      expect(result.errors).toEqual([]);
+    });
+
+    test('collects errors for invalid files', () => {
+      fsAdapter.createDir('/project/.vgc');
+
+      const validYaml = `
+metadata:
+  name: Valid
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    dataSchema:
+      name:
+        type: string
+edgeTypes:
+  call:
+    style: solid
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+
+      fsAdapter.writeFile('/project/.vgc/valid.yaml', validYaml);
+      fsAdapter.writeFile('/project/.vgc/invalid-yaml.yaml', 'invalid: yaml: content:');
+      fsAdapter.writeFile('/project/.vgc/incomplete.yaml', 'metadata:\n  name: Incomplete\nnodeTypes: {}');
+
+      const result = loader.loadAll('/project');
+
+      expect(result.configs).toHaveLength(1);
+      expect(result.configs[0].name).toBe('valid');
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+
+    test('returns configs sorted by name', () => {
+      fsAdapter.createDir('/project/.vgc');
+
+      const configTemplate = (name: string) => `
+metadata:
+  name: ${name}
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    dataSchema:
+      name:
+        type: string
+edgeTypes:
+  call:
+    style: solid
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+
+      fsAdapter.writeFile('/project/.vgc/zebra.yaml', configTemplate('Zebra'));
+      fsAdapter.writeFile('/project/.vgc/alpha.yaml', configTemplate('Alpha'));
+      fsAdapter.writeFile('/project/.vgc/middle.yaml', configTemplate('Middle'));
+
+      const result = loader.loadAll('/project');
+
+      expect(result.configs).toHaveLength(3);
+      expect(result.configs[0].name).toBe('alpha');
+      expect(result.configs[1].name).toBe('middle');
+      expect(result.configs[2].name).toBe('zebra');
+    });
+
+    test('handles mixed .yaml and .yml extensions', () => {
+      fsAdapter.createDir('/project/.vgc');
+
+      const configTemplate = (name: string) => `
+metadata:
+  name: ${name}
+  version: 1.0.0
+nodeTypes:
+  service:
+    shape: rectangle
+    dataSchema:
+      name:
+        type: string
+edgeTypes:
+  call:
+    style: solid
+allowedConnections:
+  - from: service
+    to: service
+    via: call
+`;
+
+      fsAdapter.writeFile('/project/.vgc/config1.yaml', configTemplate('Config 1'));
+      fsAdapter.writeFile('/project/.vgc/config2.yml', configTemplate('Config 2'));
+
+      const result = loader.loadAll('/project');
+
+      expect(result.configs).toHaveLength(2);
+      expect(result.errors).toEqual([]);
+    });
+  });
+
+  describe('getConfigDirectoryPath', () => {
+    test('returns correct .vgc path', () => {
+      const path = loader.getConfigDirectoryPath('/my/project');
+
+      expect(path).toBe('/my/project/.vgc');
+    });
+
+    test('handles trailing slashes', () => {
+      const path = loader.getConfigDirectoryPath('/my/project/');
+
+      // The path should be consistent regardless of trailing slash
+      expect(path).toContain('.vgc');
+    });
+  });
+});