@principal-ai/principal-view-cli 0.3.3 → 0.3.5

package/dist/commands/coverage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Coverage command - Measure telemetry coverage for canvas nodes
+ *
+ * This command analyzes .otel.canvas files and checks which nodes have
+ * OpenTelemetry instrumentation in their linked source files.
+ */
+import { Command } from 'commander';
+export declare function createCoverageCommand(): Command;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/commands/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgIpC,wBAAgB,qBAAqB,IAAI,OAAO,CAiD/C"}

package/dist/commands/coverage.js

@@ -0,0 +1,158 @@
+/**
+ * Coverage command - Measure telemetry coverage for canvas nodes
+ *
+ * This command analyzes .otel.canvas files and checks which nodes have
+ * OpenTelemetry instrumentation in their linked source files.
+ */
+import { Command } from 'commander';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { analyzeCoverage } from '@principal-ai/principal-view-core';
+/**
+ * Print coverage report in human-readable format
+ */
+function printCoverageReport(metrics, rootDir, options) {
+    const { verbose } = options;
+    console.log(chalk.bold('\n' + '─'.repeat(70)));
+    console.log(chalk.bold('📈 TELEMETRY COVERAGE REPORT'));
+    console.log(chalk.bold('─'.repeat(70)));
+    // Canvas files
+    console.log(chalk.bold(`\n📋 Canvas Files Analyzed: ${metrics.canvasFiles.length}`));
+    if (verbose) {
+        metrics.canvasFiles.forEach(f => console.log(chalk.dim(`   - ${f}`)));
+    }
+    // Node summary
+    console.log(chalk.bold('\n🎯 Node Summary:'));
+    console.log(`   Total nodes: ${metrics.totalNodes}`);
+    console.log(`   Nodes with anchors: ${chalk.cyan(metrics.nodesWithFiles.toString())}`);
+    console.log(`   Nodes without anchors: ${chalk.dim(metrics.totalNodes - metrics.nodesWithFiles)}`);
+    console.log(`   Nodes with instrumentation: ${chalk.green(metrics.nodesWithInstrumentation.toString())}`);
+    const coverageColor = metrics.coveragePercentage >= 80
+        ? chalk.green
+        : metrics.coveragePercentage >= 50
+            ? chalk.yellow
+            : chalk.red;
+    console.log(`   Coverage: ${coverageColor(metrics.coveragePercentage.toFixed(1) + '%')}`);
+    // Nodes WITHOUT anchors
+    const noAnchors = metrics.nodeCoverage.filter(n => n.filePaths.length === 0);
+    if (noAnchors.length > 0 && verbose) {
+        console.log(chalk.yellow(`\n⚠️  Nodes Without Anchors (${noAnchors.length}):`));
+        const display = verbose ? noAnchors : noAnchors.slice(0, 10);
+        display.forEach(node => {
+            console.log(chalk.dim(`   - ${node.nodeId}`));
+        });
+        if (!verbose && noAnchors.length > 10) {
+            console.log(chalk.dim(`   ... and ${noAnchors.length - 10} more (use --verbose to see all)`));
+        }
+    }
+    // Nodes WITHOUT instrumentation
+    const uninstrumented = metrics.nodeCoverage.filter(n => n.filePaths.length > 0 && !n.hasInstrumentation);
+    if (uninstrumented.length > 0) {
+        console.log(chalk.red(`\n❌ Nodes Missing Instrumentation (${uninstrumented.length}):`));
+        const display = verbose ? uninstrumented : uninstrumented.slice(0, 5);
+        display.forEach(node => {
+            console.log(chalk.yellow(`\n   Node: ${node.nodeId}`));
+            console.log(chalk.dim(`   Files: ${node.filePaths.join(', ')}`));
+        });
+        if (!verbose && uninstrumented.length > 5) {
+            console.log(chalk.dim(`\n   ... and ${uninstrumented.length - 5} more (use --verbose to see all)`));
+        }
+    }
+    // Nodes WITH instrumentation
+    const instrumented = metrics.nodeCoverage.filter(n => n.hasInstrumentation);
+    if (instrumented.length > 0) {
+        console.log(chalk.green(`\n✅ Nodes With Instrumentation (${instrumented.length}):`));
+        const display = verbose ? instrumented : instrumented.slice(0, 5);
+        display.forEach(node => {
+            console.log(chalk.dim(`   - ${node.nodeId}: ${node.instrumentedFiles.join(', ')}`));
+        });
+        if (!verbose && instrumented.length > 5) {
+            console.log(chalk.dim(`   ... and ${instrumented.length - 5} more (use --verbose to see all)`));
+        }
+    }
+    // Nodes with missing files
+    const withMissingFiles = metrics.nodeCoverage.filter(n => n.missingFiles.length > 0);
+    if (withMissingFiles.length > 0) {
+        console.log(chalk.yellow(`\n⚠️  Nodes Referencing Missing Files (${withMissingFiles.length}):`));
+        const display = verbose ? withMissingFiles : withMissingFiles.slice(0, 5);
+        display.forEach(node => {
+            console.log(chalk.dim(`   - ${node.nodeId}: ${node.missingFiles.join(', ')}`));
+        });
+        if (!verbose && withMissingFiles.length > 5) {
+            console.log(chalk.dim(`   ... and ${withMissingFiles.length - 5} more (use --verbose to see all)`));
+        }
+    }
+    // Recommendations
+    console.log(chalk.bold('\n💡 Recommendations:'));
+    if (noAnchors.length > 0) {
+        console.log(chalk.red('   🔴 Add anchors to canvas nodes before measuring coverage'));
+    }
+    else if (metrics.coveragePercentage < 30) {
+        console.log(chalk.red('   🔴 Low coverage - add OTEL instrumentation to files referenced in canvas'));
+    }
+    else if (metrics.coveragePercentage < 60) {
+        console.log(chalk.yellow('   🟡 Moderate coverage - continue instrumenting remaining nodes'));
+    }
+    else {
+        console.log(chalk.green('   🟢 Good coverage - maintain instrumentation quality'));
+    }
+    // Next steps
+    console.log(chalk.bold('\n📝 Next Steps:'));
+    if (noAnchors.length > 0) {
+        console.log(chalk.dim(`   1. Add anchors to ${noAnchors.length} node(s) without file references`));
+        console.log(chalk.dim(`   2. Example: { "id": "node-id", "anchors": [{ "path": "packages/core/src/File.ts" }] }`));
+        console.log(chalk.dim(`   3. Re-run: privu coverage`));
+    }
+    else if (uninstrumented.length > 0) {
+        console.log(chalk.dim(`   1. Review the ${uninstrumented.length} uninstrumented node(s) above`));
+        console.log(chalk.dim(`   2. Add OpenTelemetry spans to their source files`));
+        console.log(chalk.dim(`   3. Follow patterns from packages/core/src/rules/engine.ts`));
+        console.log(chalk.dim(`   4. Re-run: privu coverage`));
+    }
+    else {
+        console.log(chalk.green(`   ✅ All canvas nodes have instrumentation!`));
+    }
+    console.log(chalk.bold('\n' + '─'.repeat(70) + '\n'));
+}
+export function createCoverageCommand() {
+    const command = new Command('coverage');
+    command
+        .description('Measure telemetry coverage for canvas nodes')
+        .option('-d, --dir <path>', 'Project directory (defaults to current directory)')
+        .option('--json', 'Output results as JSON')
+        .option('-t, --threshold <percentage>', 'Minimum coverage percentage (exit with error if below)')
+        .option('-v, --verbose', 'Show all nodes in output')
+        .action(async (options) => {
+        try {
+            const rootDir = resolve(options.dir || process.cwd());
+            // Analyze coverage
+            const metrics = await analyzeCoverage(rootDir);
+            // Output results
+            if (options.json) {
+                console.log(JSON.stringify(metrics, null, 2));
+            }
+            else {
+                printCoverageReport(metrics, rootDir, options);
+            }
+            // Check threshold
+            if (options.threshold) {
+                const threshold = parseFloat(options.threshold);
+                if (isNaN(threshold) || threshold < 0 || threshold > 100) {
+                    console.error(chalk.red('Error: Threshold must be a number between 0 and 100'));
+                    process.exit(1);
+                }
+                if (metrics.coveragePercentage < threshold) {
+                    if (!options.json) {
+                        console.error(chalk.red(`\n✗ Coverage ${metrics.coveragePercentage.toFixed(1)}% is below threshold ${threshold}%`));
+                    }
+                    process.exit(1);
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Create command - Create a new canvas file in the .principal-views folder
+ */
+import { Command } from 'commander';
+export declare function createCreateCommand(): Command;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,mBAAmB,IAAI,OAAO,CAkD7C"}

package/dist/commands/create.js

@@ -0,0 +1,50 @@
+/**
+ * Create command - Create a new canvas file in the .principal-views folder
+ */
+import { Command } from 'commander';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+const TEMPLATE_CANVAS = {
+    nodes: [],
+    edges: [],
+};
+export function createCreateCommand() {
+    const command = new Command('create');
+    command
+        .description('Create a new canvas file in the .principal-views folder')
+        .requiredOption('-n, --name <name>', 'Name for the canvas file (e.g., "cache-sync-architecture")')
+        .option('-f, --force', 'Overwrite existing file')
+        .action(async (options) => {
+        try {
+            const vgcDir = join(process.cwd(), '.principal-views');
+            const canvasFile = join(vgcDir, `${options.name}.canvas`);
+            // Check if .principal-views directory exists
+            if (!existsSync(vgcDir)) {
+                mkdirSync(vgcDir, { recursive: true });
+                console.log(chalk.green(`Created directory: .principal-views/`));
+            }
+            // Check if canvas file already exists
+            if (existsSync(canvasFile) && !options.force) {
+                console.error(chalk.red(`Error: Canvas file already exists: .principal-views/${options.name}.canvas`));
+                console.log(chalk.yellow(`Use ${chalk.cyan('--force')} to overwrite`));
+                process.exit(1);
+            }
+            // Create the canvas file
+            writeFileSync(canvasFile, JSON.stringify(TEMPLATE_CANVAS, null, 2));
+            console.log(chalk.green(`✓ Created canvas file: .principal-views/${options.name}.canvas`));
+            // Show next steps
+            console.log('');
+            console.log(chalk.bold('Next steps:'));
+            console.log(`  1. Open ${chalk.cyan(`.principal-views/${options.name}.canvas`)} in your editor`);
+            console.log(`  2. Add nodes and edges to define your architecture`);
+            console.log(`  3. Run ${chalk.cyan('npx @principal-ai/principal-view-cli validate')} to check your configuration`);
+            console.log(`  4. Run ${chalk.cyan('npx @principal-ai/principal-view-cli doctor')} to verify source mappings`);
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Doctor command - Check configuration staleness and source pattern validity
+ *
+ * This command performs two types of checks:
+ * 1. Pattern validation: Ensures source patterns in .principal-views/*.yaml configs match actual files
+ * 2. Freshness check: Compares config modification times vs source file changes
+ */
+import { Command } from 'commander';
+export declare function createDoctorCommand(): Command;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmLpC,wBAAgB,mBAAmB,IAAI,OAAO,CAsK7C"}

package/dist/commands/doctor.js

@@ -0,0 +1,274 @@
+/**
+ * Doctor command - Check configuration staleness and source pattern validity
+ *
+ * This command performs two types of checks:
+ * 1. Pattern validation: Ensures source patterns in .principal-views/*.yaml configs match actual files
+ * 2. Freshness check: Compares config modification times vs source file changes
+ */
+import { Command } from 'commander';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import chalk from 'chalk';
+import { globby } from 'globby';
+import yaml from 'js-yaml';
+/**
+ * Format a time difference in human-readable form
+ */
+function formatTimeDiff(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days} day${days > 1 ? 's' : ''}`;
+    if (hours > 0)
+        return `${hours} hour${hours > 1 ? 's' : ''}`;
+    if (minutes > 0)
+        return `${minutes} minute${minutes > 1 ? 's' : ''}`;
+    return `${seconds} second${seconds !== 1 ? 's' : ''}`;
+}
+/**
+ * Check a single .principal-views config file for staleness issues
+ */
+async function checkConfig(configPath, projectRoot) {
+    const absolutePath = resolve(configPath);
+    const relativePath = relative(projectRoot, absolutePath);
+    const issues = [];
+    const stats = {
+        nodeTypesChecked: 0,
+        patternsChecked: 0,
+        filesMatched: 0,
+        staleConfigs: 0,
+    };
+    let configName = 'Unknown';
+    try {
+        const content = readFileSync(absolutePath, 'utf8');
+        const config = yaml.load(content);
+        const configStats = statSync(absolutePath);
+        const configMtime = configStats.mtime.getTime();
+        configName = config.metadata?.name || relativePath;
+        // Check if config has nodeTypes with sources
+        if (!config.nodeTypes || Object.keys(config.nodeTypes).length === 0) {
+            issues.push({
+                type: 'info',
+                configFile: relativePath,
+                message: 'No node types defined in configuration',
+            });
+            return { configFile: relativePath, configName, issues, stats };
+        }
+        // Check each node type's source patterns
+        for (const [nodeTypeName, nodeType] of Object.entries(config.nodeTypes)) {
+            stats.nodeTypesChecked++;
+            if (!nodeType.sources || nodeType.sources.length === 0) {
+                issues.push({
+                    type: 'info',
+                    configFile: relativePath,
+                    nodeType: nodeTypeName,
+                    message: `Node type "${nodeTypeName}" has no source patterns defined`,
+                });
+                continue;
+            }
+            for (const pattern of nodeType.sources) {
+                stats.patternsChecked++;
+                // Find files matching this pattern
+                const matchedFiles = await globby(pattern, {
+                    cwd: projectRoot,
+                    gitignore: true,
+                    ignore: ['node_modules/**', 'dist/**', '.git/**'],
+                });
+                if (matchedFiles.length === 0) {
+                    // Pattern doesn't match any files - this is a warning
+                    issues.push({
+                        type: 'warning',
+                        configFile: relativePath,
+                        nodeType: nodeTypeName,
+                        message: `Source pattern "${pattern}" doesn't match any files`,
+                        details: 'This pattern may be outdated or the files may have been moved/deleted',
+                    });
+                }
+                else {
+                    stats.filesMatched += matchedFiles.length;
+                    // Check if any matched files are newer than the config
+                    let newestFile = null;
+                    let newestMtime = 0;
+                    for (const file of matchedFiles) {
+                        const filePath = resolve(projectRoot, file);
+                        try {
+                            const fileStats = statSync(filePath);
+                            const fileMtime = fileStats.mtime.getTime();
+                            if (fileMtime > newestMtime) {
+                                newestMtime = fileMtime;
+                                newestFile = file;
+                            }
+                        }
+                        catch {
+                            // File may have been deleted between glob and stat
+                        }
+                    }
+                    // Check staleness (with 5-second buffer for build tools)
+                    const STALE_THRESHOLD_MS = 5000;
+                    if (newestFile && newestMtime > configMtime + STALE_THRESHOLD_MS) {
+                        const timeDiff = newestMtime - configMtime;
+                        stats.staleConfigs++;
+                        issues.push({
+                            type: 'warning',
+                            configFile: relativePath,
+                            nodeType: nodeTypeName,
+                            message: `Config may be stale: "${newestFile}" was modified ${formatTimeDiff(timeDiff)} after the config`,
+                            details: `Pattern: ${pattern} (matched ${matchedFiles.length} file${matchedFiles.length > 1 ? 's' : ''})`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        issues.push({
+            type: 'error',
+            configFile: relativePath,
+            message: `Failed to parse config: ${error.message}`,
+        });
+    }
+    return { configFile: relativePath, configName, issues, stats };
+}
+export function createDoctorCommand() {
+    const command = new Command('doctor');
+    command
+        .description('Check configuration staleness and source pattern validity')
+        .option('-q, --quiet', 'Only show errors and warnings')
+        .option('--errors-only', 'Only show errors (for pre-commit hooks)')
+        .option('--json', 'Output results as JSON')
+        .option('-d, --dir <path>', 'Project directory (defaults to current directory)')
+        .action(async (options) => {
+        try {
+            const projectRoot = resolve(options.dir || process.cwd());
+            const vgcDir = resolve(projectRoot, '.principal-views');
+            if (!existsSync(vgcDir)) {
+                if (options.json) {
+                    console.log(JSON.stringify({ error: 'No .principal-views directory found', results: [] }));
+                }
+                else {
+                    console.log(chalk.yellow('No .principal-views directory found.'));
+                    console.log(chalk.dim('Run "npx @principal-ai/principal-view-cli init" to create a configuration.'));
+                }
+                return;
+            }
+            // Find all .yaml config files
+            const configFiles = await globby(['*.yaml', '*.yml'], {
+                cwd: vgcDir,
+                absolute: true,
+                ignore: ['README.md'],
+            });
+            if (configFiles.length === 0) {
+                if (options.json) {
+                    console.log(JSON.stringify({ error: 'No config files found in .principal-views', results: [] }));
+                }
+                else {
+                    console.log(chalk.yellow('No configuration files found in .principal-views/'));
+                }
+                return;
+            }
+            // Check each config
+            const results = [];
+            for (const configFile of configFiles) {
+                const result = await checkConfig(configFile, projectRoot);
+                results.push(result);
+            }
+            // Aggregate stats
+            const totalStats = results.reduce((acc, r) => ({
+                nodeTypesChecked: acc.nodeTypesChecked + r.stats.nodeTypesChecked,
+                patternsChecked: acc.patternsChecked + r.stats.patternsChecked,
+                filesMatched: acc.filesMatched + r.stats.filesMatched,
+                staleConfigs: acc.staleConfigs + r.stats.staleConfigs,
+            }), { nodeTypesChecked: 0, patternsChecked: 0, filesMatched: 0, staleConfigs: 0 });
+            // Filter issues based on options
+            const filterIssues = (issues) => {
+                if (options.errorsOnly) {
+                    return issues.filter((i) => i.type === 'error');
+                }
+                if (options.quiet) {
+                    return issues.filter((i) => i.type === 'error' || i.type === 'warning');
+                }
+                return issues;
+            };
+            // Count issues
+            const allIssues = results.flatMap((r) => filterIssues(r.issues));
+            const errorCount = allIssues.filter((i) => i.type === 'error').length;
+            const warningCount = allIssues.filter((i) => i.type === 'warning').length;
+            // Output results
+            if (options.json) {
+                console.log(JSON.stringify({
+                    results: results.map((r) => ({
+                        ...r,
+                        issues: filterIssues(r.issues),
+                    })),
+                    summary: {
+                        configs: results.length,
+                        errors: errorCount,
+                        warnings: warningCount,
+                        ...totalStats,
+                    },
+                }, null, 2));
+            }
+            else {
+                if (!options.quiet && !options.errorsOnly) {
+                    console.log(chalk.bold(`\nChecking ${results.length} configuration file(s)...\n`));
+                }
+                for (const result of results) {
+                    const issues = filterIssues(result.issues);
+                    if (issues.length === 0 && !options.quiet && !options.errorsOnly) {
+                        console.log(chalk.green(`✓ ${result.configFile}`) + chalk.dim(` (${result.configName})`));
+                        continue;
+                    }
+                    if (issues.length > 0) {
+                        const hasErrors = issues.some((i) => i.type === 'error');
+                        const icon = hasErrors ? chalk.red('✗') : chalk.yellow('⚠');
+                        console.log(`${icon} ${result.configFile}` + chalk.dim(` (${result.configName})`));
+                        for (const issue of issues) {
+                            const prefix = issue.nodeType ? `[${issue.nodeType}] ` : '';
+                            if (issue.type === 'error') {
+                                console.log(chalk.red(`  ✗ ${prefix}${issue.message}`));
+                            }
+                            else if (issue.type === 'warning') {
+                                console.log(chalk.yellow(`  ⚠ ${prefix}${issue.message}`));
+                            }
+                            else {
+                                console.log(chalk.dim(`  ℹ ${prefix}${issue.message}`));
+                            }
+                            if (issue.details) {
+                                console.log(chalk.dim(`    → ${issue.details}`));
+                            }
+                        }
+                        console.log('');
+                    }
+                }
+                // Summary
+                if (!options.errorsOnly) {
+                    console.log(chalk.dim('─'.repeat(50)));
+                    console.log(chalk.dim(`Checked ${totalStats.nodeTypesChecked} node types, ` +
+                        `${totalStats.patternsChecked} patterns, ` +
+                        `matched ${totalStats.filesMatched} files`));
+                }
+                if (errorCount > 0) {
+                    console.log(chalk.red(`\n✗ ${errorCount} error(s) found`));
+                    process.exit(1);
+                }
+                else if (warningCount > 0 && options.errorsOnly) {
+                    // In errors-only mode, don't fail on warnings
+                    process.exit(0);
+                }
+                else if (warningCount > 0) {
+                    console.log(chalk.yellow(`\n⚠ ${warningCount} warning(s) found`));
+                }
+                else if (!options.quiet && !options.errorsOnly) {
+                    console.log(chalk.green(`\n✓ All configurations are up to date`));
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/formats.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Formats command - Display documentation about file formats
+ */
+import { Command } from 'commander';
+export declare function createFormatsCommand(): Command;
+//# sourceMappingURL=formats.d.ts.map

package/dist/commands/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../../src/commands/formats.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAycpC,wBAAgB,oBAAoB,IAAI,OAAO,CA6B9C"}