@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/dist/discovery/CanvasDiscovery.js

@@ -1,865 +0,0 @@
-"use strict";
-/**
- * Unified discovery system for canvas and execution files in a package-aware way
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CanvasDiscovery = void 0;
-const codebase_composition_1 = require("@principal-ai/codebase-composition");
-const edge_derivation_1 = require("../workflow/edge-derivation");
-const canvas_1 = require("../types/canvas");
-const OtelCanvasValidator_1 = require("../validation/OtelCanvasValidator");
-/**
- * Unified discovery system for canvas and execution files in a package-aware way
- *
- * @example
- * // Basic usage without content parsing
- * const discovery = new CanvasDiscovery();
- * const result = await discovery.discover(fileTree);
- *
- * @example
- * // With content parsing (CLI)
- * const result = await discovery.discover(fileTree, {
- *   fileReader: async (path) => fs.promises.readFile(path, 'utf-8'),
- *   includeContent: true
- * });
- *
- * @example
- * // With content parsing (panels)
- * const result = await discovery.discover(fileTree, {
- *   fileReader: async (path) => context.getSlice('fileCache').read(path),
- *   includeContent: true
- * });
- */
-class CanvasDiscovery {
-    constructor() {
-        this.packageCache = new Map();
-        this.packageModule = new codebase_composition_1.PackageLayerModule();
-    }
-    /**
-     * Build a lookup map from span pattern to span info from spans.canvas files
-     *
-     * @param canvases - Discovered canvases (must include content for spans.canvas)
-     * @returns Map of spanPattern → { label?, scope? }
-     */
-    buildSpanLookup(canvases) {
-        const lookup = new Map();
-        for (const canvas of canvases) {
-            // Only process spans.canvas files with content
-            if (canvas.type !== 'spans')
-                continue;
-            const canvasWithContent = canvas;
-            const content = canvasWithContent.content;
-            if (!content?.nodes)
-                continue;
-            // Extract span patterns, labels, and scopes from otel-span-convention nodes
-            for (const node of content.nodes) {
-                if ((0, canvas_1.isOtelSpanConventionNode)(node)) {
-                    const spanPattern = node.otel?.spanPattern;
-                    if (spanPattern) {
-                        lookup.set(spanPattern, {
-                            label: node.label,
-                            scope: node.otel?.scope,
-                        });
-                    }
-                }
-            }
-        }
-        return lookup;
-    }
-    /**
-     * Build a lookup map from scope name to display label from scopes.canvas files
-     *
-     * @param canvases - Discovered canvases (must include content for scopes.canvas)
-     * @returns Map of scopeName → label
-     */
-    buildScopeLabelLookup(canvases) {
-        const lookup = new Map();
-        for (const canvas of canvases) {
-            // Only process scopes.canvas files with content
-            if (canvas.type !== 'scopes')
-                continue;
-            const canvasWithContent = canvas;
-            const content = canvasWithContent.content;
-            if (!content?.nodes)
-                continue;
-            // Extract scope names and labels from otel-scope nodes
-            for (const node of content.nodes) {
-                if ((0, canvas_1.isOtelScopeNode)(node)) {
-                    const scopeName = node.otel.scope;
-                    const label = node.label;
-                    if (scopeName && label) {
-                        lookup.set(scopeName, label);
-                    }
-                }
-            }
-        }
-        return lookup;
-    }
-    /**
-     * Discover all canvas, workflow, and test trace files in the file tree
-     *
-     * @param fileTree - FileTree from repository-abstraction
-     * @param options - Discovery options (fileReader, includeContent)
-     * @returns Discovery result with canvases, testTraces, storyboards, and errors
-     */
-    async discover(fileTree, options = {}) {
-        const errors = [];
-        const warnings = [];
-        // 1. Discover packages (with caching by fileTree.sha)
-        const packages = await this.discoverPackagesWithCache(fileTree, options.fileReader);
-        // 2. Build package lookup map for efficient path matching
-        const packageMap = this.buildPackageMap(packages);
-        // 3. Discover canvas files
-        const canvases = await this.discoverCanvasFiles(fileTree, packageMap, options, errors);
-        // 3.5. Build span lookup from spans.canvas files (for enriching workflow referencedSpans with labels and scopes)
-        const spanLookup = this.buildSpanLookup(canvases);
-        // 3.6. Build scope label lookup from scopes.canvas files (for resolving scope display names)
-        const scopeLabelLookup = this.buildScopeLabelLookup(canvases);
-        // 4. Discover storyboards (hierarchical organization)
-        // Note: Test traces are discovered as part of workflows, not separately
-        const storyboards = await this.discoverStoryboards(fileTree, packageMap, canvases, options, errors, spanLookup, scopeLabelLookup);
-        // 5. Collect all test traces from workflows for backward compatibility
-        const testTraces = [];
-        for (const storyboard of storyboards) {
-            for (const workflow of storyboard.workflows) {
-                testTraces.push(...workflow.testTraces);
-            }
-        }
-        // 6. Discover dashboard files from .principal-views/dashboards/
-        const dashboards = await this.discoverDashboards(fileTree, packageMap, options, errors);
-        // 7. Detect legacy flat canvas structures and add deprecation errors
-        this.detectLegacyStructures(canvases, storyboards, errors);
-        // 8. Validate required canvas types
-        this.validateRequiredCanvases(canvases, storyboards, errors);
-        // 8.5. Validate scope hierarchy (when content is loaded)
-        if (options.includeContent) {
-            this.validateScopeHierarchy(storyboards, spanLookup, scopeLabelLookup, errors);
-        }
-        // 9. Sort results
-        canvases.sort(this.compareByPackageThenName);
-        testTraces.sort(this.compareByPackageThenName);
-        storyboards.sort(this.compareByPackageThenName);
-        dashboards.sort(this.compareByPackageThenName);
-        return { canvases, testTraces, storyboards, dashboards, errors, warnings };
-    }
-    /**
-     * Clear package cache (useful when file tree changes)
-     */
-    clearCache() {
-        this.packageCache.clear();
-    }
-    /**
-     * Check if a file path is relevant to canvas discovery
-     * Uses package-aware path matching for .principal-views directories
-     */
-    isRelevantPath(path) {
-        // Canvas files (.canvas, .otel.canvas)
-        if (this.isInCanvasDir(path) && this.parseCanvasPath(path)) {
-            return true;
-        }
-        // Workflow files (.workflow.json) in .principal-views
-        if (path.includes(CanvasDiscovery.CANVAS_DIR) && path.endsWith(CanvasDiscovery.WORKFLOW_EXTENSION)) {
-            return true;
-        }
-        // Dashboard files (.dashboard.json) in .principal-views
-        if (path.includes(CanvasDiscovery.CANVAS_DIR) && path.endsWith(CanvasDiscovery.DASHBOARD_EXTENSION)) {
-            return true;
-        }
-        // Test trace files (.otel.json) in .principal-views
-        if (path.includes(CanvasDiscovery.CANVAS_DIR) && path.endsWith('.otel.json')) {
-            return true;
-        }
-        return false;
-    }
-    /**
-     * Get all file paths in the FileTree that are relevant to canvas discovery
-     * Uses package-aware path matching (respects packages/\*\/.principal-views/ etc.)
-     *
-     * @param fileTree - FileTree from repository-abstraction
-     * @returns Set of relevant file paths
-     */
-    getRelevantPaths(fileTree) {
-        const paths = new Set();
-        for (const file of fileTree.allFiles) {
-            const path = file.relativePath || file.path || '';
-            if (this.isRelevantPath(path)) {
-                paths.add(path);
-            }
-        }
-        return paths;
-    }
-    /**
-     * Filter git status to only include changes relevant to canvas discovery
-     *
-     * For existing/modified/deleted files: filters to paths in the current FileTree's relevant paths
-     * For new/untracked files: checks if they match discovery patterns (could be new canvas files)
-     *
-     * @param fileTree - FileTree from repository-abstraction
-     * @param gitStatus - Git status with file lists
-     * @returns Filtered git status containing only relevant changes, or null if no relevant changes
-     */
-    filterRelevantGitChanges(fileTree, gitStatus) {
-        const relevantPaths = this.getRelevantPaths(fileTree);
-        // For existing files: filter to paths we know about
-        const filterExisting = (paths) => paths.filter(p => relevantPaths.has(p));
-        // For new/untracked files: check if they match discovery patterns
-        const filterNew = (paths) => paths.filter(p => this.isRelevantPath(p));
-        const filtered = {
-            ...gitStatus,
-            modifiedFiles: filterExisting(gitStatus.modifiedFiles),
-            stagedFiles: filterNew(gitStatus.stagedFiles),
-            untrackedFiles: filterNew(gitStatus.untrackedFiles),
-            deletedFiles: filterExisting(gitStatus.deletedFiles),
-            createdFiles: filterNew(gitStatus.createdFiles || []),
-        };
-        // Return null if no relevant changes
-        const hasChanges = filtered.modifiedFiles.length > 0 ||
-            filtered.stagedFiles.length > 0 ||
-            filtered.untrackedFiles.length > 0 ||
-            filtered.deletedFiles.length > 0 ||
-            filtered.createdFiles.length > 0;
-        return hasChanges ? filtered : null;
-    }
-    /**
-     * Discover storyboards (hierarchical organization of canvas + workflows + executions)
-     */
-    async discoverStoryboards(fileTree, packageMap, canvases, options, errors, spanLookup, scopeLabelLookup) {
-        const storyboards = [];
-        // Build a map of directories to check for storyboards
-        const storyboardDirs = new Map();
-        // Find all directories in .principal-views/ that have subdirectories
-        for (const file of fileTree.allFiles) {
-            const path = file.relativePath || file.path || '';
-            const parts = path.split('/');
-            // Look for paths like: .principal-views/storyboard-name/workflow-name/...
-            // Or: packages/subsystems-core/.principal-views/storyboard-name/workflow-name/...
-            const pvIndex = parts.indexOf(CanvasDiscovery.CANVAS_DIR);
-            if (pvIndex === -1 || parts.length < pvIndex + 3)
-                continue;
-            const storyboardName = parts[pvIndex + 1];
-            const storyboardPath = parts.slice(0, pvIndex + 2).join('/');
-            if (!storyboardDirs.has(storyboardPath)) {
-                storyboardDirs.set(storyboardPath, new Set());
-            }
-            storyboardDirs.get(storyboardPath).add(storyboardName);
-        }
-        // For each potential storyboard directory, check if it has a canvas
-        for (const [storyboardPath, storyboardNames] of storyboardDirs) {
-            for (const storyboardName of storyboardNames) {
-                // Skip __executions__ directory (legacy pattern, should not exist)
-                if (storyboardName === '__executions__')
-                    continue;
-                // Find canvas for this storyboard
-                const storyboardCanvas = canvases.find(c => {
-                    const canvasDir = c.path.split('/').slice(0, -1).join('/');
-                    return canvasDir === storyboardPath && c.basename === storyboardName;
-                });
-                if (!storyboardCanvas)
-                    continue;
-                // This is a storyboard! Now discover workflows
-                const workflows = await this.discoverWorkflowsInStoryboard(fileTree, storyboardPath, storyboardName, packageMap, options, spanLookup, scopeLabelLookup, errors);
-                // Determine package context
-                const packageInfo = this.findPackageForPath(storyboardPath, packageMap);
-                // Generate unique ID
-                const id = packageInfo
-                    ? `${packageInfo.packageData.name}/${storyboardName}`
-                    : storyboardName;
-                // Create discovered storyboard
-                const storyboard = {
-                    id,
-                    name: this.toDisplayName(storyboardName),
-                    path: storyboardPath,
-                    basename: storyboardName,
-                    canvas: storyboardCanvas,
-                    workflows,
-                    packageName: packageInfo?.packageData.name,
-                    packagePath: packageInfo?.packageData.path,
-                    scope: packageInfo ? 'package' : 'root',
-                };
-                storyboards.push(storyboard);
-            }
-        }
-        // Add standalone canvas files (flat structure without workflows)
-        // These are typically .canvas files used for documentation/architecture diagrams
-        const storyboardCanvasIds = new Set(storyboards.map(s => s.canvas.id));
-        for (const canvas of canvases) {
-            // Skip if already part of a hierarchical storyboard
-            if (storyboardCanvasIds.has(canvas.id))
-                continue;
-            // Check if canvas is in flat structure (.principal-views/file.canvas)
-            const canvasDir = canvas.path.split('/').slice(0, -1).join('/');
-            const parts = canvasDir.split('/');
-            const pvIndex = parts.indexOf(CanvasDiscovery.CANVAS_DIR);
-            // Only include flat .canvas files (for documentation)
-            // Exclude .otel.canvas files which must use storyboard structure
-            if (pvIndex !== -1 && parts.length === pvIndex + 1 && canvas.type !== 'otel') {
-                const packageInfo = this.findPackageForPath(canvas.path, packageMap);
-                // Create a standalone storyboard with no workflows
-                const storyboard = {
-                    id: canvas.id,
-                    name: canvas.name,
-                    path: canvasDir,
-                    basename: canvas.basename,
-                    canvas: canvas,
-                    workflows: [],
-                    packageName: packageInfo?.packageData.name,
-                    packagePath: packageInfo?.packageData.path,
-                    scope: packageInfo ? 'package' : 'root',
-                };
-                storyboards.push(storyboard);
-            }
-        }
-        return storyboards;
-    }
-    /**
-     * Discover workflows within a storyboard folder
-     */
-    async discoverWorkflowsInStoryboard(fileTree, storyboardPath, storyboardName, packageMap, options, spanLookup, scopeLabelLookup, errors) {
-        const workflows = [];
-        // Find all workflow files in this storyboard
-        for (const file of fileTree.allFiles) {
-            const path = file.relativePath || file.path || '';
-            // Check if file is in this storyboard
-            if (!path.startsWith(storyboardPath + '/'))
-                continue;
-            // Check if it's a workflow file
-            if (!path.endsWith(CanvasDiscovery.WORKFLOW_EXTENSION))
-                continue;
-            // Extract workflow info
-            const filename = path.split('/').pop();
-            if (!filename)
-                continue;
-            const basename = filename.replace(CanvasDiscovery.WORKFLOW_EXTENSION, '');
-            const workflowDir = path.split('/').slice(0, -1).join('/');
-            // Determine package context
-            const packageInfo = this.findPackageForPath(path, packageMap);
-            // Generate unique ID (basename only - storyboard context is in storyboardId)
-            const id = basename;
-            // Discover test traces co-located in the same directory as workflow.json
-            const workflowTestTraces = await this.discoverTestTracesInWorkflowDir(fileTree, workflowDir, packageMap, options, errors);
-            // Create discovered workflow
-            let workflow = {
-                id,
-                name: this.toDisplayName(basename),
-                path,
-                basename,
-                storyboardId: packageInfo
-                    ? `${packageInfo.packageData.name}/${storyboardName}`
-                    : storyboardName,
-                packageName: packageInfo?.packageData.name,
-                packagePath: packageInfo?.packageData.path,
-                scope: packageInfo ? 'package' : 'root',
-                testTraces: workflowTestTraces,
-            };
-            // Optionally load content
-            if (options.includeContent && options.fileReader) {
-                try {
-                    const content = await options.fileReader(path);
-                    const parsedContent = JSON.parse(content);
-                    // Extract referenced spans from workflow content
-                    const edgeResult = (0, edge_derivation_1.deriveWorkflowEdges)(parsedContent, path);
-                    // Convert span patterns to ReferencedSpan objects with labels and scopes
-                    const referencedSpans = edgeResult.referencedSpans.map((pattern) => {
-                        const spanInfo = spanLookup.get(pattern);
-                        return {
-                            pattern,
-                            label: spanInfo?.label,
-                            scope: spanInfo?.scope,
-                        };
-                    });
-                    // Derive workflow instrumentation scope from rootSpan's scope
-                    const rootSpan = parsedContent.rootSpan;
-                    const rootSpanInfo = rootSpan ? spanLookup.get(rootSpan) : undefined;
-                    const instrumentationScope = rootSpanInfo?.scope;
-                    const instrumentationScopeLabel = instrumentationScope
-                        ? scopeLabelLookup.get(instrumentationScope)
-                        : undefined;
-                    workflow = {
-                        ...workflow,
-                        content: parsedContent,
-                        referencedSpans,
-                        instrumentationScope,
-                        instrumentationScopeLabel,
-                    };
-                }
-                catch (error) {
-                    errors.push({
-                        path,
-                        error: `Failed to parse workflow content: ${error.message}`,
-                    });
-                }
-            }
-            workflows.push(workflow);
-        }
-        return workflows;
-    }
-    /**
-     * Discover execution files co-located in a workflow directory
-     */
-    async discoverTestTracesInWorkflowDir(fileTree, workflowDir, packageMap, options, errors) {
-        const testTraces = [];
-        // Find all .otel.json files in the workflow directory
-        for (const file of fileTree.allFiles) {
-            const path = file.relativePath || file.path || '';
-            // Check if file is in this workflow directory
-            const fileDir = path.split('/').slice(0, -1).join('/');
-            if (fileDir !== workflowDir)
-                continue;
-            // Check if it's a test trace file (.otel.json)
-            if (!path.endsWith('.otel.json')) {
-                continue;
-            }
-            // Extract test trace metadata
-            const filename = path.split('/').pop();
-            if (!filename)
-                continue;
-            const basename = filename.replace('.otel.json', '');
-            // Determine package context
-            const packageInfo = this.findPackageForPath(path, packageMap);
-            // Generate unique ID (workflow-scoped)
-            const workflowBasename = workflowDir.split('/').pop() || '';
-            const id = packageInfo
-                ? `${packageInfo.packageData.name}/${workflowBasename}/${basename}`
-                : `${workflowBasename}/${basename}`;
-            // Create discovered test trace
-            let testTrace = {
-                id,
-                name: this.toDisplayName(basename),
-                path,
-                basename,
-                type: 'otel',
-                canvasBasename: basename,
-                packageName: packageInfo?.packageData.name,
-                packagePath: packageInfo?.packageData.path,
-                scope: packageInfo ? 'package' : 'root',
-            };
-            // Optionally load content
-            if (options.includeContent && options.fileReader) {
-                try {
-                    const content = await options.fileReader(path);
-                    testTrace = { ...testTrace, content: JSON.parse(content) };
-                }
-                catch (error) {
-                    errors.push({
-                        path,
-                        error: `Failed to parse test trace content: ${error.message}`,
-                    });
-                }
-            }
-            testTraces.push(testTrace);
-        }
-        return testTraces;
-    }
-    /**
-     * Discover packages with caching by fileTree SHA
-     */
-    async discoverPackagesWithCache(fileTree, fileReader) {
-        const cacheKey = fileTree.sha;
-        if (this.packageCache.has(cacheKey)) {
-            return this.packageCache.get(cacheKey);
-        }
-        const packages = await this.packageModule.discoverPackages(fileTree, fileReader);
-        this.packageCache.set(cacheKey, packages);
-        return packages;
-    }
-    /**
-     * Build package lookup map for efficient path matching
-     */
-    buildPackageMap(packages) {
-        const map = new Map();
-        for (const pkg of packages) {
-            // Normalize package path for lookup (replace backslashes with forward slashes)
-            const normalizedPath = pkg.packageData.path.replace(/\\/g, '/');
-            map.set(normalizedPath, pkg);
-        }
-        return map;
-    }
-    /**
-     * Discover canvas files in the file tree
-     */
-    async discoverCanvasFiles(fileTree, packageMap, options, errors) {
-        const canvases = [];
-        for (const file of fileTree.allFiles) {
-            const path = file.relativePath || file.path || '';
-            // Check if in .principal-views directory
-            if (!this.isInCanvasDir(path))
-                continue;
-            // Extract canvas metadata
-            const metadata = this.parseCanvasPath(path);
-            if (!metadata)
-                continue;
-            // Determine package context
-            const packageInfo = this.findPackageForPath(path, packageMap);
-            // Generate unique ID
-            // Include canvas type suffix for non-regular types to avoid collisions
-            // e.g., "architecture" vs "architecture.scopes"
-            const idSuffix = metadata.type !== 'regular' ? `.${metadata.type}` : '';
-            const id = packageInfo
-                ? `${packageInfo.packageData.name}/${metadata.basename}${idSuffix}`
-                : `${metadata.basename}${idSuffix}`;
-            // Create discovered canvas
-            const canvas = {
-                id,
-                name: this.toDisplayName(metadata.basename),
-                path,
-                basename: metadata.basename,
-                type: metadata.type,
-                packageName: packageInfo?.packageData.name,
-                packagePath: packageInfo?.packageData.path,
-                scope: packageInfo ? 'package' : 'root',
-            };
-            // Optionally load content
-            if (options.includeContent && options.fileReader) {
-                try {
-                    const content = await options.fileReader(path);
-                    const parsedContent = JSON.parse(content);
-                    // Cast to DiscoveredCanvasWithContent when adding content
-                    const canvasWithContent = canvas;
-                    canvasWithContent.content = parsedContent;
-                    // Validate OTEL canvas nodes for explicit color usage (only for .otel.canvas files)
-                    if (metadata.type === 'otel') {
-                        const otelValidator = new OtelCanvasValidator_1.OtelCanvasValidator();
-                        const violations = otelValidator.validate(parsedContent, path);
-                        for (const violation of violations) {
-                            errors.push({
-                                path: violation.file,
-                                error: `[${violation.ruleId}] ${violation.message}. ${violation.impact} ${violation.suggestion}`,
-                            });
-                        }
-                    }
-                    // Extract markdown path from canvas metadata if it exists
-                    if (parsedContent.markdown) {
-                        canvas.markdownPath = parsedContent.markdown;
-                    }
-                }
-                catch (error) {
-                    errors.push({
-                        path,
-                        error: `Failed to parse canvas content: ${error.message}`,
-                    });
-                }
-            }
-            canvases.push(canvas);
-        }
-        return canvases;
-    }
-    /**
-     * Discover execution files in the file tree
-     */
-    /**
-     * Check if path is in .principal-views directory
-     * Supports both flat (.principal-views/file.canvas) and hierarchical (.principal-views/storyboard/file.canvas) structures
-     */
-    isInCanvasDir(path) {
-        const parts = path.split('/');
-        // Root flat: .principal-views/file.canvas (2 parts)
-        if (parts[0] === CanvasDiscovery.CANVAS_DIR && parts.length === 2) {
-            return true;
-        }
-        // Root hierarchical: .principal-views/storyboard/file.canvas (3 parts)
-        if (parts[0] === CanvasDiscovery.CANVAS_DIR && parts.length === 3) {
-            return true;
-        }
-        // Package structures
-        if (parts.includes(CanvasDiscovery.CANVAS_DIR)) {
-            const idx = parts.indexOf(CanvasDiscovery.CANVAS_DIR);
-            // Package flat: packages/subsystems-core/.principal-views/file.canvas (idx + 2 parts)
-            // Package hierarchical: packages/subsystems-core/.principal-views/storyboard/file.canvas (idx + 3 parts)
-            return parts.length === idx + 2 || parts.length === idx + 3;
-        }
-        return false;
-    }
-    /**
-     * Parse canvas file path to extract metadata
-     */
-    parseCanvasPath(path) {
-        const filename = path.split('/').pop();
-        if (!filename)
-            return null;
-        // Check for .scopes.canvas first (must come before .canvas check)
-        if (filename.endsWith('.scopes.canvas')) {
-            return {
-                basename: filename.replace(/\.scopes\.canvas$/, ''),
-                type: 'scopes',
-            };
-        }
-        // Check for .resources.canvas (must come before .canvas check)
-        if (filename.endsWith('.resources.canvas')) {
-            return {
-                basename: filename.replace(/\.resources\.canvas$/, ''),
-                type: 'resources',
-            };
-        }
-        // Check for .spans.canvas (must come before .canvas check)
-        if (filename.endsWith('.spans.canvas')) {
-            return {
-                basename: filename.replace(/\.spans\.canvas$/, ''),
-                type: 'spans',
-            };
-        }
-        // Check for .events.canvas (must come before .canvas check)
-        if (filename.endsWith('.events.canvas')) {
-            return {
-                basename: filename.replace(/\.events\.canvas$/, ''),
-                type: 'events',
-            };
-        }
-        // Check for .otel.canvas (must come before .canvas check)
-        if (filename.endsWith('.otel.canvas')) {
-            return {
-                basename: filename.replace(/\.otel\.canvas$/, ''),
-                type: 'otel',
-            };
-        }
-        // Check for .canvas (but not .otel.canvas, .scopes.canvas, .resources.canvas, .spans.canvas, or .events.canvas)
-        if (filename.endsWith('.canvas')) {
-            const basename = filename.replace(/\.canvas$/, '');
-            // Handle special case: files named exactly "resources.canvas" or "spans.canvas"
-            // These are architecture canvases despite using .canvas extension
-            if (basename === 'resources') {
-                return { basename, type: 'resources' };
-            }
-            if (basename === 'spans') {
-                return { basename, type: 'spans' };
-            }
-            if (basename === 'scopes') {
-                return { basename, type: 'scopes' };
-            }
-            if (basename === 'events') {
-                return { basename, type: 'events' };
-            }
-            return { basename, type: 'regular' };
-        }
-        return null;
-    }
-    /**
-     * Find package for a given path using longest-path matching
-     */
-    findPackageForPath(path, packageMap) {
-        // Find the longest matching package path
-        let bestMatch = null;
-        let bestMatchLength = 0;
-        for (const [pkgPath, pkg] of packageMap) {
-            if (path.startsWith(pkgPath + '/')) {
-                if (pkgPath.length > bestMatchLength) {
-                    bestMatch = pkg;
-                    bestMatchLength = pkgPath.length;
-                }
-            }
-        }
-        return bestMatch;
-    }
-    /**
-     * Convert basename to display name (Title Case)
-     */
-    toDisplayName(basename) {
-        return basename
-            .split('-')
-            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-            .join(' ');
-    }
-    /**
-     * Sort by package then name
-     */
-    compareByPackageThenName(a, b) {
-        // Package files first, then root
-        if (a.packageName && !b.packageName)
-            return -1;
-        if (!a.packageName && b.packageName)
-            return 1;
-        // If both have packages, sort by package name
-        if (a.packageName && b.packageName) {
-            const pkgCompare = a.packageName.localeCompare(b.packageName);
-            if (pkgCompare !== 0)
-                return pkgCompare;
-        }
-        // Within same package/root, sort by name
-        return a.name.localeCompare(b.name);
-    }
-    /**
-     * Validate required canvas types based on dependency chain:
-     * - resources.canvas is required (foundation)
-     * - spans.canvas is required when resources.canvas exists
-     * - .otel.canvas is required when spans.canvas exists
-     */
-    validateRequiredCanvases(canvases, storyboards, errors) {
-        // Check canvas types by category
-        const hasResourcesCanvas = canvases.some(c => c.type === 'resources');
-        const hasSpansCanvas = canvases.some(c => c.type === 'spans');
-        // Check for otel canvases specifically (not just any storyboard, since standalone canvases also create storyboards)
-        const hasOtelCanvas = canvases.some(c => c.type === 'otel');
-        // If no canvases at all, nothing to validate (no .principal-views directory)
-        if (canvases.length === 0 && storyboards.length === 0) {
-            return;
-        }
-        // 1. resources.canvas is required (foundation)
-        if (!hasResourcesCanvas) {
-            errors.push({
-                path: '.principal-views',
-                error: 'Missing required resources.canvas: A resources canvas documenting OTEL resources and scopes is required. ' +
-                    'Create .principal-views/resources.canvas (or architecture.resources.canvas) with nodes showing service.name and instrumentation scopes.',
-            });
-            // Don't check further dependencies if foundation is missing
-            return;
-        }
-        // 2. spans.canvas is required when resources.canvas exists
-        if (!hasSpansCanvas) {
-            errors.push({
-                path: '.principal-views',
-                error: 'Missing required spans.canvas: When resources.canvas exists, a spans canvas documenting span conventions is required. ' +
-                    'Create .principal-views/architecture.spans.canvas with nodes for each span pattern (e.g., validate.*, http.request) and edges showing valid parent-child relationships.',
-            });
-            // Don't check further dependencies
-            return;
-        }
-        // 3. .otel.canvas is required when spans.canvas exists
-        if (!hasOtelCanvas) {
-            errors.push({
-                path: '.principal-views',
-                error: 'Missing required .otel.canvas: When spans.canvas exists, at least one feature-level OTEL canvas is required. ' +
-                    'Create a storyboard with an .otel.canvas file (e.g., .principal-views/my-feature/my-feature.otel.canvas) documenting events for a specific feature.',
-            });
-        }
-    }
-    /**
-     * Discover dashboard files from .principal-views/dashboards/ folder
-     */
-    async discoverDashboards(fileTree, packageMap, options, errors) {
-        const dashboards = [];
-        for (const file of fileTree.allFiles) {
-            const path = file.relativePath || file.path || '';
-            // Only look for .dashboard.json files in dashboards/ folder
-            if (!path.endsWith(CanvasDiscovery.DASHBOARD_EXTENSION))
-                continue;
-            // Must be in .principal-views/dashboards/ folder
-            const parts = path.split('/');
-            const pvIndex = parts.indexOf(CanvasDiscovery.CANVAS_DIR);
-            if (pvIndex === -1)
-                continue;
-            // Check if it's in the dashboards/ folder (directly after .principal-views/)
-            const nextPart = parts[pvIndex + 1];
-            if (nextPart !== 'dashboards')
-                continue;
-            const filename = parts[parts.length - 1];
-            const basename = filename.replace(/\.dashboard\.json$/, '');
-            // Determine package context
-            const packageInfo = this.findPackageForPath(path, packageMap);
-            // Generate unique ID
-            const id = packageInfo
-                ? `${packageInfo.packageData.name}/${basename}`
-                : basename;
-            const dashboard = {
-                id,
-                name: this.toDisplayName(basename),
-                path,
-                basename,
-                packageName: packageInfo?.packageData.name,
-                packagePath: packageInfo?.packageData.path,
-                scope: packageInfo ? 'package' : 'root',
-            };
-            // Optionally load content
-            if (options.includeContent && options.fileReader) {
-                try {
-                    const content = await options.fileReader(path);
-                    const parsed = JSON.parse(content);
-                    dashboard.content = parsed;
-                }
-                catch (e) {
-                    errors.push({
-                        path,
-                        error: `Failed to parse dashboard: ${e instanceof Error ? e.message : String(e)}`,
-                    });
-                }
-            }
-            dashboards.push(dashboard);
-        }
-        return dashboards;
-    }
-    /**
-     * Detect legacy flat canvas structures and add deprecation errors
-     * Note: Flat .canvas and .scopes.canvas files are supported
-     * Only .otel.canvas files in flat structure are deprecated
-     */
-    detectLegacyStructures(canvases, storyboards, errors) {
-        // Build a set of storyboard canvas IDs for quick lookup
-        const storyboardCanvasIds = new Set(storyboards.map(s => s.canvas.id));
-        // Check for legacy flat .otel.canvas files (not part of any storyboard)
-        // Note: Flat .canvas and .scopes.canvas files are supported
-        for (const canvas of canvases) {
-            if (!storyboardCanvasIds.has(canvas.id)) {
-                // This canvas is not part of any storyboard
-                const canvasDir = canvas.path.split('/').slice(0, -1).join('/');
-                const parts = canvasDir.split('/');
-                const pvIndex = parts.indexOf(CanvasDiscovery.CANVAS_DIR);
-                // Only error if it's a .otel.canvas file in flat structure
-                // Regular .canvas and .scopes.canvas files in flat structure are supported
-                if (pvIndex !== -1 && parts.length === pvIndex + 1 && canvas.type === 'otel') {
-                    errors.push({
-                        path: canvas.path,
-                        error: 'DEPRECATED: Flat .otel.canvas files are no longer supported. .otel.canvas files must use the storyboard structure (.principal-views/storyboard-name/storyboard-name.otel.canvas). For static documentation, use .canvas files instead.',
-                    });
-                }
-            }
-        }
-    }
-    /**
-     * Validate scope hierarchy for hierarchical filtering
-     *
-     * Validates:
-     * 1. Workflow rootSpan exists in spans.canvas
-     * 2. Span conventions have otel.scope defined
-     * 3. Scope references exist in scopes.canvas (warning)
-     */
-    validateScopeHierarchy(storyboards, spanLookup, scopeLabelLookup, errors) {
-        // Track scopes that have been warned about (to avoid duplicate warnings)
-        const warnedScopes = new Set();
-        for (const storyboard of storyboards) {
-            // Only validate otel storyboards
-            if (storyboard.canvas.type !== 'otel')
-                continue;
-            for (const workflow of storyboard.workflows) {
-                const workflowWithContent = workflow;
-                const content = workflowWithContent.content;
-                if (!content)
-                    continue;
-                const rootSpan = content.rootSpan;
-                if (!rootSpan)
-                    continue;
-                // 1. Validate rootSpan exists in spans.canvas
-                const rootSpanInfo = spanLookup.get(rootSpan);
-                if (!rootSpanInfo) {
-                    errors.push({
-                        path: workflow.path,
-                        error: `Workflow "${workflow.basename}" has rootSpan "${rootSpan}" but no matching span convention ` +
-                            `was found in spans.canvas. Add an otel-span-convention node with spanPattern: "${rootSpan}".`,
-                    });
-                    continue; // Skip further validation for this workflow
-                }
-                // 2. Validate span convention has otel.scope defined
-                if (!rootSpanInfo.scope) {
-                    errors.push({
-                        path: workflow.path,
-                        error: `Span convention "${rootSpan}" in spans.canvas does not declare a scope. ` +
-                            `Add otel.scope to specify which instrumentation scope creates this span.`,
-                    });
-                    continue; // Skip further validation for this workflow
-                }
-                // 3. Warn if scope doesn't exist in scopes.canvas
-                const scopeName = rootSpanInfo.scope;
-                if (!scopeLabelLookup.has(scopeName) && !warnedScopes.has(scopeName)) {
-                    warnedScopes.add(scopeName);
-                    errors.push({
-                        path: workflow.path,
-                        error: `Span convention "${rootSpan}" references scope "${scopeName}" but no matching ` +
-                            `otel-scope node was found in scopes.canvas. Consider adding it for documentation.`,
-                    });
-                }
-            }
-        }
-    }
-}
-CanvasDiscovery.CANVAS_DIR = '.principal-views';
-CanvasDiscovery.WORKFLOW_EXTENSION = '.workflow.json';
-CanvasDiscovery.DASHBOARD_EXTENSION = '.dashboard.json';
-exports.CanvasDiscovery = CanvasDiscovery;
-//# sourceMappingURL=CanvasDiscovery.js.map