@soulcraft/brainy 3.17.0 → 3.18.0

package/dist/vfs/semantic/ProjectionStrategy.js

@@ -0,0 +1,40 @@
+/**
+ * Projection Strategy Interface
+ *
+ * Defines how to map semantic path dimensions to Brainy queries
+ * Each strategy uses EXISTING Brainy indexes and methods
+ */
+/**
+ * Base class for projection strategies with common utilities
+ */
+export class BaseProjectionStrategy {
+    /**
+     * Convert Brainy Results to entity IDs
+     * Helper method for subclasses
+     */
+    extractIds(results) {
+        return results.map(r => r.id);
+    }
+    /**
+     * Verify that an entity is a file (not directory)
+     * Uses REAL Brainy.get() method
+     */
+    async isFile(brain, entityId) {
+        const entity = await brain.get(entityId);
+        return entity?.metadata?.vfsType === 'file';
+    }
+    /**
+     * Filter entity IDs to only include files
+     * Uses REAL Brainy.get() for each entity
+     */
+    async filterFiles(brain, entityIds) {
+        const files = [];
+        for (const id of entityIds) {
+            if (await this.isFile(brain, id)) {
+                files.push(id);
+            }
+        }
+        return files;
+    }
+}
+//# sourceMappingURL=ProjectionStrategy.js.map

package/dist/vfs/semantic/SemanticPathParser.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Semantic Path Parser
+ *
+ * Parses semantic filesystem paths into structured queries
+ * PURE LOGIC - No external dependencies, no async operations
+ *
+ * Supported path formats:
+ * - Traditional: /src/auth.ts
+ * - By Concept: /by-concept/authentication/login.ts
+ * - By Author: /by-author/alice/file.ts
+ * - By Time: /as-of/2024-03-15/file.ts
+ * - By Relationship: /related-to/src/auth.ts/depth-2
+ * - By Similarity: /similar-to/src/auth.ts/threshold-0.8
+ * - By Tag: /by-tag/security/file.ts
+ */
+export type SemanticDimension = 'traditional' | 'concept' | 'author' | 'time' | 'relationship' | 'similar' | 'tag';
+export interface ParsedSemanticPath {
+    dimension: SemanticDimension;
+    value: string | Date | RelationshipValue | SimilarityValue;
+    subpath?: string;
+    filters?: Record<string, any>;
+}
+export interface RelationshipValue {
+    targetPath: string;
+    depth?: number;
+    relationshipTypes?: string[];
+}
+export interface SimilarityValue {
+    targetPath: string;
+    threshold?: number;
+}
+/**
+ * Semantic Path Parser
+ * Parses various semantic path formats into structured data
+ */
+export declare class SemanticPathParser {
+    private static readonly PATTERNS;
+    /**
+     * Parse a path into semantic components
+     * PURE FUNCTION - no external calls, no async
+     */
+    parse(path: string): ParsedSemanticPath;
+    /**
+     * Check if a path is semantic (non-traditional)
+     */
+    isSemanticPath(path: string): boolean;
+    /**
+     * Get the dimension type from a path
+     */
+    getDimension(path: string): SemanticDimension;
+    /**
+     * Normalize a path - remove trailing slashes, collapse multiple slashes
+     * PURE FUNCTION
+     */
+    private normalizePath;
+    /**
+     * Parse date string (YYYY-MM-DD) into Date object
+     * PURE FUNCTION
+     */
+    private parseDate;
+    /**
+     * Validate parsed path structure
+     */
+    validate(parsed: ParsedSemanticPath): boolean;
+    /**
+     * Parse relationship paths: /related-to/<path>/depth-N/types-X,Y/<subpath>
+     */
+    private parseRelationshipPath;
+    /**
+     * Parse similarity paths: /similar-to/<path>/threshold-N/<subpath>
+     */
+    private parseSimilarityPath;
+}

package/dist/vfs/semantic/SemanticPathParser.js

@@ -0,0 +1,285 @@
+/**
+ * Semantic Path Parser
+ *
+ * Parses semantic filesystem paths into structured queries
+ * PURE LOGIC - No external dependencies, no async operations
+ *
+ * Supported path formats:
+ * - Traditional: /src/auth.ts
+ * - By Concept: /by-concept/authentication/login.ts
+ * - By Author: /by-author/alice/file.ts
+ * - By Time: /as-of/2024-03-15/file.ts
+ * - By Relationship: /related-to/src/auth.ts/depth-2
+ * - By Similarity: /similar-to/src/auth.ts/threshold-0.8
+ * - By Tag: /by-tag/security/file.ts
+ */
+/**
+ * Semantic Path Parser
+ * Parses various semantic path formats into structured data
+ */
+export class SemanticPathParser {
+    /**
+     * Parse a path into semantic components
+     * PURE FUNCTION - no external calls, no async
+     */
+    parse(path) {
+        if (!path || typeof path !== 'string') {
+            throw new Error('Path must be a non-empty string');
+        }
+        // Normalize path
+        const normalized = this.normalizePath(path);
+        // Try concept dimension
+        const conceptMatch = normalized.match(SemanticPathParser.PATTERNS.concept);
+        if (conceptMatch) {
+            return {
+                dimension: 'concept',
+                value: conceptMatch[1],
+                subpath: conceptMatch[2]
+            };
+        }
+        // Try author dimension
+        const authorMatch = normalized.match(SemanticPathParser.PATTERNS.author);
+        if (authorMatch) {
+            return {
+                dimension: 'author',
+                value: authorMatch[1],
+                subpath: authorMatch[2]
+            };
+        }
+        // Try time dimension
+        const timeMatch = normalized.match(SemanticPathParser.PATTERNS.time);
+        if (timeMatch) {
+            const dateStr = timeMatch[1];
+            const date = this.parseDate(dateStr);
+            return {
+                dimension: 'time',
+                value: date,
+                subpath: timeMatch[2]
+            };
+        }
+        // Try relationship dimension
+        if (normalized.startsWith('/related-to/')) {
+            return this.parseRelationshipPath(normalized);
+        }
+        // Try similarity dimension
+        if (normalized.startsWith('/similar-to/')) {
+            return this.parseSimilarityPath(normalized);
+        }
+        // Try tag dimension
+        const tagMatch = normalized.match(SemanticPathParser.PATTERNS.tag);
+        if (tagMatch) {
+            return {
+                dimension: 'tag',
+                value: tagMatch[1],
+                subpath: tagMatch[2]
+            };
+        }
+        // Default to traditional path
+        return {
+            dimension: 'traditional',
+            value: normalized
+        };
+    }
+    /**
+     * Check if a path is semantic (non-traditional)
+     */
+    isSemanticPath(path) {
+        if (!path || typeof path !== 'string') {
+            return false;
+        }
+        const normalized = this.normalizePath(path);
+        // Check if matches any semantic pattern
+        return (normalized.startsWith('/by-concept/') ||
+            normalized.startsWith('/by-author/') ||
+            normalized.startsWith('/as-of/') ||
+            normalized.startsWith('/related-to/') ||
+            normalized.startsWith('/similar-to/') ||
+            normalized.startsWith('/by-tag/'));
+    }
+    /**
+     * Get the dimension type from a path
+     */
+    getDimension(path) {
+        return this.parse(path).dimension;
+    }
+    /**
+     * Normalize a path - remove trailing slashes, collapse multiple slashes
+     * PURE FUNCTION
+     */
+    normalizePath(path) {
+        // Remove trailing slash (except for root)
+        let normalized = path.replace(/\/+$/, '');
+        // Collapse multiple slashes
+        normalized = normalized.replace(/\/+/g, '/');
+        // Ensure starts with /
+        if (!normalized.startsWith('/')) {
+            normalized = '/' + normalized;
+        }
+        // Special case: empty path becomes /
+        if (normalized === '') {
+            normalized = '/';
+        }
+        return normalized;
+    }
+    /**
+     * Parse date string (YYYY-MM-DD) into Date object
+     * PURE FUNCTION
+     */
+    parseDate(dateStr) {
+        const parts = dateStr.split('-');
+        if (parts.length !== 3) {
+            throw new Error(`Invalid date format: ${dateStr}. Expected YYYY-MM-DD`);
+        }
+        const year = parseInt(parts[0], 10);
+        const month = parseInt(parts[1], 10) - 1; // Months are 0-indexed in JS
+        const day = parseInt(parts[2], 10);
+        if (isNaN(year) || isNaN(month) || isNaN(day)) {
+            throw new Error(`Invalid date format: ${dateStr}. Expected YYYY-MM-DD`);
+        }
+        if (year < 1900 || year > 2100) {
+            throw new Error(`Invalid year: ${year}. Expected 1900-2100`);
+        }
+        if (month < 0 || month > 11) {
+            throw new Error(`Invalid month: ${month + 1}. Expected 1-12`);
+        }
+        if (day < 1 || day > 31) {
+            throw new Error(`Invalid day: ${day}. Expected 1-31`);
+        }
+        return new Date(year, month, day);
+    }
+    /**
+     * Validate parsed path structure
+     */
+    validate(parsed) {
+        if (!parsed || typeof parsed !== 'object') {
+            return false;
+        }
+        if (!parsed.dimension) {
+            return false;
+        }
+        if (parsed.value === undefined || parsed.value === null) {
+            return false;
+        }
+        // Dimension-specific validation
+        switch (parsed.dimension) {
+            case 'time':
+                return parsed.value instanceof Date && !isNaN(parsed.value.getTime());
+            case 'relationship':
+                const relValue = parsed.value;
+                return typeof relValue.targetPath === 'string' && relValue.targetPath.length > 0;
+            case 'similar':
+                const simValue = parsed.value;
+                return typeof simValue.targetPath === 'string' && simValue.targetPath.length > 0;
+            default:
+                return typeof parsed.value === 'string' && parsed.value.length > 0;
+        }
+    }
+    /**
+     * Parse relationship paths: /related-to/<path>/depth-N/types-X,Y/<subpath>
+     */
+    parseRelationshipPath(path) {
+        // Remove /related-to/ prefix
+        const withoutPrefix = path.substring('/related-to/'.length);
+        // Split into segments
+        const segments = withoutPrefix.split('/');
+        let targetPath = '';
+        let depth;
+        let types;
+        let subpath;
+        let i = 0;
+        // Collect path segments until we hit depth-, types-, or end
+        while (i < segments.length) {
+            const segment = segments[i];
+            if (segment.startsWith('depth-')) {
+                depth = parseInt(segment.substring('depth-'.length), 10);
+                i++;
+                continue;
+            }
+            if (segment.startsWith('types-')) {
+                types = segment.substring('types-'.length).split(',');
+                i++;
+                continue;
+            }
+            // If we've already collected the target path and found depth/types,
+            // rest is subpath
+            if (targetPath && (depth !== undefined || types !== undefined)) {
+                subpath = segments.slice(i).join('/');
+                break;
+            }
+            // Add to target path
+            if (targetPath) {
+                targetPath += '/' + segment;
+            }
+            else {
+                targetPath = segment;
+            }
+            i++;
+        }
+        const value = {
+            targetPath,
+            depth,
+            relationshipTypes: types
+        };
+        return {
+            dimension: 'relationship',
+            value,
+            subpath
+        };
+    }
+    /**
+     * Parse similarity paths: /similar-to/<path>/threshold-N/<subpath>
+     */
+    parseSimilarityPath(path) {
+        // Remove /similar-to/ prefix
+        const withoutPrefix = path.substring('/similar-to/'.length);
+        // Split into segments
+        const segments = withoutPrefix.split('/');
+        let targetPath = '';
+        let threshold;
+        let subpath;
+        let i = 0;
+        // Collect path segments until we hit threshold- or end
+        while (i < segments.length) {
+            const segment = segments[i];
+            if (segment.startsWith('threshold-')) {
+                threshold = parseFloat(segment.substring('threshold-'.length));
+                i++;
+                // Rest is subpath
+                if (i < segments.length) {
+                    subpath = segments.slice(i).join('/');
+                }
+                break;
+            }
+            // Add to target path
+            if (targetPath) {
+                targetPath += '/' + segment;
+            }
+            else {
+                targetPath = segment;
+            }
+            i++;
+        }
+        const value = {
+            targetPath,
+            threshold
+        };
+        return {
+            dimension: 'similar',
+            value,
+            subpath
+        };
+    }
+}
+// Regex patterns for each dimension
+SemanticPathParser.PATTERNS = {
+    concept: /^\/by-concept\/([^\/]+)(?:\/(.+))?$/,
+    author: /^\/by-author\/([^\/]+)(?:\/(.+))?$/,
+    time: /^\/as-of\/(\d{4}-\d{2}-\d{2})(?:\/(.+))?$/,
+    // Relationship: /related-to/<path>/depth-N/types-X,Y/<subpath>
+    // Must handle paths with slashes, so capture everything before /depth- or /types-
+    relationship: /^\/related-to\/(.+?)(?:\/depth-(\d+)|\/types-([^\/]+)|\/(.+))*$/,
+    // Similarity: /similar-to/<path>/threshold-N/<subpath>
+    similar: /^\/similar-to\/(.+?)(?:\/threshold-([\d.]+)|\/(.+))*$/,
+    tag: /^\/by-tag\/([^\/]+)(?:\/(.+))?$/
+};
+//# sourceMappingURL=SemanticPathParser.js.map

package/dist/vfs/semantic/SemanticPathResolver.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Semantic Path Resolver
+ *
+ * Unified path resolver that handles BOTH:
+ * - Traditional hierarchical paths (/src/auth/login.ts)
+ * - Semantic projection paths (/by-concept/authentication/...)
+ *
+ * Uses EXISTING infrastructure:
+ * - PathResolver for traditional paths
+ * - ProjectionRegistry for semantic dimensions
+ * - SemanticPathParser for path type detection
+ */
+import { Brainy } from '../../brainy.js';
+import { VirtualFileSystem } from '../VirtualFileSystem.js';
+import { VFSEntity } from '../types.js';
+import { ProjectionRegistry } from './ProjectionRegistry.js';
+/**
+ * Semantic Path Resolver
+ * Handles both traditional and semantic paths transparently
+ *
+ * Uses Brainy's UnifiedCache for optimal memory management and performance
+ */
+export declare class SemanticPathResolver {
+    private brain;
+    private vfs;
+    private pathResolver;
+    private parser;
+    private registry;
+    private cache;
+    constructor(brain: Brainy, vfs: VirtualFileSystem, rootEntityId: string, registry: ProjectionRegistry);
+    /**
+     * Resolve a path to entity ID(s)
+     * Handles BOTH traditional and semantic paths
+     *
+     * For traditional paths: Returns single entity ID
+     * For semantic paths: Returns first matching entity ID
+     *
+     * Uses UnifiedCache with request coalescing to prevent stampede
+     *
+     * @param path - Path to resolve (traditional or semantic)
+     * @param options - Resolution options
+     * @returns Entity ID
+     */
+    resolve(path: string, options?: {
+        followSymlinks?: boolean;
+        cache?: boolean;
+    }): Promise<string>;
+    /**
+     * Resolve semantic path to multiple entity IDs
+     * This is the polymorphic resolution that returns ALL matches
+     *
+     * Uses UnifiedCache for performance
+     *
+     * @param path - Semantic path
+     * @param options - Resolution options
+     * @returns Array of entity IDs
+     */
+    resolveAll(path: string, options?: {
+        cache?: boolean;
+        limit?: number;
+    }): Promise<string[]>;
+    /**
+     * Internal semantic path resolution (called by cache)
+     * Estimates cost and size for UnifiedCache optimization
+     */
+    private resolveSemanticPathInternal;
+    /**
+     * Filter entity IDs by subpath (filename or partial path)
+     */
+    private filterBySubpath;
+    /**
+     * Get children of a directory
+     * Delegates to PathResolver for traditional directories
+     * For semantic paths, returns entities in that dimension
+     */
+    getChildren(dirIdOrPath: string): Promise<VFSEntity[]>;
+    /**
+     * List entities in a semantic dimension
+     */
+    private listSemanticDimension;
+    /**
+     * Create a path mapping (cache a path resolution)
+     * Only applies to traditional paths
+     */
+    createPath(path: string, entityId: string): Promise<void>;
+    /**
+     * Invalidate path cache
+     */
+    invalidatePath(path: string, recursive?: boolean): void;
+    /**
+     * Clear all semantic caches
+     * Uses UnifiedCache's clear method
+     */
+    invalidateSemanticCache(): void;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): void;
+}