@principal-ai/subsystems-core 0.29.0

package/dist/telemetry/coverage.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * Telemetry Coverage Analysis
+ *
+ * Measures observability coverage by analyzing which implementation files
+ * contain the OpenTelemetry events documented in canvas nodes.
+ *
+ * Uses codebase-composition's ImplementationFileLayerModule for accurate,
+ * framework-aware detection of implementation files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCoverage = void 0;
+const CanvasDiscovery_1 = require("../discovery/CanvasDiscovery");
+const canvas_1 = require("../types/canvas");
+const builder_1 = require("../storyboard/builder");
+const codebase_composition_1 = require("@principal-ai/codebase-composition");
+/**
+ * Extract event name from a canvas node
+ * Uses the canonical getNodeEventName() which supports all event reference formats
+ */
+function getEventName(node) {
+    return (0, builder_1.getNodeEventName)(node) ?? null;
+}
+/**
+ * Extract instrumentation file paths from a canvas node
+ * Supports both new format (node.otel.files) and legacy format (pv.otel.files)
+ */
+function getInstrumentationFiles(node) {
+    // Check OTEL nodes (top-level otel field)
+    if ((0, canvas_1.isOtelNode)(node) && node.otel?.files) {
+        return node.otel.files;
+    }
+    // Check standard nodes (pv.otel.files)
+    if ((0, canvas_1.isStandardCanvasNode)(node) && node.pv?.otel?.files) {
+        return node.pv.otel.files;
+    }
+    return [];
+}
+/**
+ * Check if a file contains a specific event name (simple string match)
+ */
+async function fileContainsEvent(filePath, eventName, fileReader) {
+    try {
+        const content = await fileReader(filePath);
+        return content.includes(eventName);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the status of a node (returns undefined if not specified)
+ * Supports both new format (node.otel.status) and legacy format (pv.status)
+ */
+function getNodeStatus(node) {
+    // Check OTEL nodes (otel.status)
+    if ((0, canvas_1.isOtelNode)(node) && node.otel?.status) {
+        return node.otel.status;
+    }
+    // Check standard nodes (pv.status)
+    if ((0, canvas_1.isStandardCanvasNode)(node) && node.pv?.status) {
+        return node.pv.status;
+    }
+    return undefined;
+}
+/**
+ * Get the scope from a node
+ * Only supports new format (node.otel.scope). Legacy format (pv.otel.scope) is rejected.
+ */
+function getNodeScope(node) {
+    const otelNode = node;
+    return otelNode.otel?.scope;
+}
+/**
+ * Build a map of file -> expected events from canvas nodes
+ * Only includes nodes with status='implemented'
+ */
+async function buildFileEventMap(otelCanvases) {
+    const fileEventMap = new Map();
+    for (const canvas of otelCanvases) {
+        if (!canvas.content?.nodes || canvas.content.nodes.length === 0) {
+            continue;
+        }
+        for (const node of canvas.content.nodes) {
+            const eventName = getEventName(node);
+            if (!eventName)
+                continue;
+            // Only check implemented nodes for coverage
+            const status = getNodeStatus(node);
+            if (status !== 'implemented')
+                continue;
+            const files = getInstrumentationFiles(node);
+            for (const file of files) {
+                if (!fileEventMap.has(file)) {
+                    fileEventMap.set(file, new Set());
+                }
+                fileEventMap.get(file).add(eventName);
+            }
+        }
+    }
+    return fileEventMap;
+}
+/**
+ * Validate nodes and collect validation errors
+ */
+function validateNodes(otelCanvases) {
+    const errors = [];
+    const statusBreakdown = {
+        missingStatusCount: 0,
+        draftCount: 0,
+        approvedCount: 0,
+        approvedWithFilesCount: 0,
+        implementedCount: 0,
+        implementedWithFilesCount: 0,
+    };
+    for (const canvas of otelCanvases) {
+        if (!canvas.content?.nodes || canvas.content.nodes.length === 0) {
+            continue;
+        }
+        for (const node of canvas.content.nodes) {
+            const status = getNodeStatus(node);
+            const eventName = getEventName(node);
+            // Only validate nodes with events
+            if (!eventName)
+                continue;
+            const files = getInstrumentationFiles(node);
+            const hasFiles = files.length > 0;
+            // Validate: nodes with events MUST have a status
+            if (!status) {
+                statusBreakdown.missingStatusCount++;
+                errors.push({
+                    nodeId: node.id,
+                    canvasPath: canvas.path,
+                    error: `Node with event "${eventName}" must have pv.status field. Set to "draft" (design phase), "approved" (ready to implement), or "implemented" (code exists)`,
+                });
+                continue; // Skip further validation for this node
+            }
+            // Get references for grounding validation
+            let references = [];
+            if ((0, canvas_1.isOtelNode)(node) && node.otel?.references) {
+                references = node.otel.references;
+            }
+            else if ((0, canvas_1.isStandardCanvasNode)(node) && node.pv?.references) {
+                references = node.pv.references;
+            }
+            const hasReferences = references.length > 0;
+            // Count by status
+            if (status === 'draft') {
+                statusBreakdown.draftCount++;
+                // Drafts must be grounded: require either files (if implementation location is known) or references
+                if (!hasFiles && !hasReferences) {
+                    errors.push({
+                        nodeId: node.id,
+                        canvasPath: canvas.path,
+                        status,
+                        error: `Node with status="draft" must have either pv.otel.files (if implementation location is known) or pv.references (to ground the event in something)`,
+                    });
+                }
+            }
+            else if (status === 'approved') {
+                statusBreakdown.approvedCount++;
+                if (hasFiles) {
+                    statusBreakdown.approvedWithFilesCount++;
+                }
+            }
+            else if (status === 'implemented') {
+                statusBreakdown.implementedCount++;
+                if (hasFiles) {
+                    statusBreakdown.implementedWithFilesCount++;
+                }
+            }
+            // Validate approved and implemented nodes have pv.otel.files
+            if ((status === 'approved' || status === 'implemented') && !hasFiles) {
+                errors.push({
+                    nodeId: node.id,
+                    canvasPath: canvas.path,
+                    status,
+                    error: `Node with status="${status}" must have pv.otel.files specified`,
+                });
+            }
+            // Error if using deprecated pv.otel.scope (only for standard nodes)
+            let legacyScope;
+            if ((0, canvas_1.isStandardCanvasNode)(node)) {
+                legacyScope = node.pv?.otel?.scope;
+            }
+            if (legacyScope) {
+                errors.push({
+                    nodeId: node.id,
+                    canvasPath: canvas.path,
+                    status,
+                    error: `Node uses deprecated "pv.otel.scope" field. Use new format: convert to type: "otel-event" with top-level "otel.scope" field instead. Run: npx @principal-ai/principal-studio-cli migrate-nodes`,
+                });
+            }
+            // Require scope for ALL event nodes (using new format)
+            const scope = getNodeScope(node);
+            if (!scope) {
+                errors.push({
+                    nodeId: node.id,
+                    canvasPath: canvas.path,
+                    status,
+                    error: `Event node must have otel.scope specified. Scope defines which instrumentation library emits this event (e.g., "terminal-activity", "auth"). Document scopes in your .scopes.canvas file with otel-scope nodes.`,
+                });
+            }
+        }
+    }
+    return { statusBreakdown, errors };
+}
+/**
+ * Analyze instrumentation for a single file
+ */
+async function analyzeFileInstrumentation(filePath, expectedEvents, fileReader, isImplFile) {
+    const foundEvents = [];
+    for (const eventName of expectedEvents) {
+        const found = await fileContainsEvent(filePath, eventName, fileReader);
+        if (found) {
+            foundEvents.push(eventName);
+        }
+    }
+    const missingEvents = expectedEvents.filter(e => !foundEvents.includes(e));
+    return {
+        filePath,
+        expectedEvents,
+        foundEvents,
+        instrumentationCount: foundEvents.length,
+        hasInstrumentation: foundEvents.length > 0,
+        missingEvents,
+        isImplementationFile: isImplFile,
+    };
+}
+/**
+ * Get implementation files using codebase-composition's ImplementationFileLayerModule
+ * This provides accurate detection with framework-awareness and package boundaries
+ */
+async function getImplementationFilesFromLayer(fileTree) {
+    // Detect packages
+    const packageModule = new codebase_composition_1.PackageLayerModule();
+    const packageLayers = await packageModule.discoverPackages(fileTree);
+    // Get implementation files per package
+    const implModule = new codebase_composition_1.ImplementationFileLayerModule();
+    const implLayers = implModule.createImplementationFileLayers(packageLayers, fileTree);
+    // Flatten to set of file paths
+    const files = new Set();
+    for (const layer of implLayers) {
+        for (const file of layer.implementationData.implementationFiles) {
+            files.add(file);
+        }
+    }
+    return { files, layers: implLayers };
+}
+/**
+ * Generate telemetry coverage report from canvas files
+ *
+ * Uses codebase-composition's ImplementationFileLayerModule for accurate,
+ * framework-aware detection of implementation files.
+ *
+ * @param fileTree - FileTree representation of the codebase
+ * @param fileReader - Function to read file contents
+ * @returns Coverage metrics based on file instrumentation
+ *
+ * @example
+ * ```typescript
+ * import { FilesystemService, NodeFileSystemAdapter } from '@principal-ai/codebase-composition/node';
+ * import { readFile } from 'fs/promises';
+ * import { resolve } from 'path';
+ *
+ * const service = new FilesystemService(new NodeFileSystemAdapter());
+ * const fileTree = await service.buildFileSystemTreeFromPath('/path/to/project');
+ * const fileReader = async (path: string) => readFile(resolve('/path/to/project', path), 'utf-8');
+ * const metrics = await analyzeCoverage(fileTree, fileReader);
+ * ```
+ */
+async function analyzeCoverage(fileTree, fileReader) {
+    // Use CanvasDiscovery to find all canvas files
+    const discovery = new CanvasDiscovery_1.CanvasDiscovery();
+    const result = await discovery.discover(fileTree, {
+        fileReader,
+        includeContent: true, // Need content to parse nodes
+    });
+    // Filter for .otel.canvas files only
+    const otelCanvases = result.canvases.filter(c => c.type === 'otel');
+    // Validate nodes and collect status breakdown
+    const { statusBreakdown, errors } = validateNodes(otelCanvases);
+    // Build map of file -> expected events from canvas (only implemented nodes)
+    const fileEventMap = await buildFileEventMap(otelCanvases);
+    // Get all implementation files from the codebase using implementation layer
+    const { files: implementationFiles, layers: implLayers } = await getImplementationFilesFromLayer(fileTree);
+    // Get all files referenced in canvas (for coverage denominator)
+    const referencedFiles = new Set(fileEventMap.keys());
+    // Combine: we want to check all files referenced in canvas that are also implementation files
+    const filesToCheck = new Set([...referencedFiles].filter(f => implementationFiles.has(f)));
+    // Analyze each file
+    const fileCoverage = [];
+    for (const filePath of filesToCheck) {
+        const expectedEvents = Array.from(fileEventMap.get(filePath) || []);
+        const coverage = await analyzeFileInstrumentation(filePath, expectedEvents, fileReader, implementationFiles.has(filePath));
+        fileCoverage.push(coverage);
+    }
+    // Calculate metrics
+    const filesWithInstrumentation = fileCoverage.filter(f => f.hasInstrumentation).length;
+    const totalImplementationFiles = filesToCheck.size;
+    const coveragePercentage = totalImplementationFiles > 0
+        ? (filesWithInstrumentation / totalImplementationFiles) * 100
+        : 0;
+    const totalExpectedEvents = fileCoverage.reduce((sum, f) => sum + f.expectedEvents.length, 0);
+    const totalFoundEvents = fileCoverage.reduce((sum, f) => sum + f.foundEvents.length, 0);
+    // Calculate per-package metrics
+    const packageCoverage = implLayers.map(layer => {
+        const packageFiles = new Set(layer.implementationData.implementationFiles);
+        const packageInstrumented = fileCoverage.filter(f => packageFiles.has(f.filePath) && f.hasInstrumentation);
+        return {
+            packageName: layer.implementationData.packageName,
+            packagePath: layer.implementationData.packagePath,
+            totalFiles: layer.implementationData.fileCount,
+            filesWithInstrumentation: packageInstrumented.length,
+            coveragePercentage: layer.implementationData.fileCount > 0
+                ? (packageInstrumented.length / layer.implementationData.fileCount) * 100
+                : 0,
+            filesByExtension: layer.implementationData.filesByExtension || {},
+        };
+    });
+    return {
+        totalImplementationFiles,
+        filesWithInstrumentation,
+        coveragePercentage,
+        fileCoverage,
+        canvasFiles: otelCanvases.map(c => c.path),
+        totalExpectedEvents,
+        totalFoundEvents,
+        packageCoverage,
+        nodeStatus: statusBreakdown,
+        validationErrors: errors,
+    };
+}
+exports.analyzeCoverage = analyzeCoverage;
+//# sourceMappingURL=coverage.js.map

package/dist/telemetry/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/telemetry/coverage.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/event-validator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Event Validator
+ *
+ * Type-safe telemetry event validation against canvas event schemas.
+ * Ensures that emitted events match the schema defined in the canvas.
+ */
+import type { ExtendedCanvas, PVEventSchema } from '../types/canvas';
+import type { ComponentLibrary } from '../types/library';
+import type { JsonObject } from '../types';
+/**
+ * Validation error for telemetry events
+ */
+export declare class EventValidationError extends Error {
+    eventName: string;
+    nodeId: string;
+    errors: string[];
+    constructor(eventName: string, nodeId: string, errors: string[]);
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Event validator that checks events against canvas schema
+ */
+export declare class EventValidator {
+    private eventSchemasByNode;
+    private eventSchemasByName;
+    private nodeIdsByBaseId;
+    private library?;
+    constructor(canvas: ExtendedCanvas, library?: ComponentLibrary);
+    /**
+     * Index all event schemas from canvas nodes
+     */
+    private indexEventSchemas;
+    /**
+     * Resolve an event schema from library by event name
+     */
+    private resolveLibraryEvent;
+    /**
+     * Validate an event against the schema for a specific node
+     */
+    validate(nodeId: string, eventName: string, attributes: JsonObject): ValidationResult;
+    /**
+     * Get the type of a value
+     */
+    private getValueType;
+    /**
+     * Get event schema for a node
+     */
+    getNodeSchema(nodeId: string): PVEventSchema | undefined;
+    /**
+     * Get event name for a node
+     */
+    getNodeEventName(nodeId: string): string | undefined;
+    /**
+     * Get all event names for a node (including related nodes with same base ID)
+     */
+    getNodeEventNames(nodeId: string): string[];
+    /**
+     * Check if a node has event schema defined
+     * Supports both exact node IDs and base IDs (without numeric suffixes)
+     */
+    hasSchema(nodeId: string): boolean;
+}
+/**
+ * Create a validated event emitter for a specific node
+ *
+ * @example
+ * ```typescript
+ * const emit = createValidatedEmitter(validator, 'graph-converter', span);
+ *
+ * // Type-safe and runtime-validated
+ * emit('conversion.started', {
+ *   'config.nodeTypes': nodeTypes.length,
+ *   'config.edgeTypes': edgeTypes.length
+ * });
+ * ```
+ */
+export declare function createValidatedEmitter(validator: EventValidator, nodeId: string, addEventFn: (eventName: string, attributes: JsonObject) => void, options?: {
+    strict?: boolean;
+}): (eventName: string, attributes: JsonObject) => void;
+//# sourceMappingURL=event-validator.d.ts.map

package/dist/telemetry/event-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-validator.d.ts","sourceRoot":"","sources":["../../src/telemetry/event-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtD;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAEpC,SAAS,EAAE,MAAM;IACjB,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,MAAM,EAAE;gBAFhB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EAAE;CAK1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,eAAe,CAAuC;IAC9D,OAAO,CAAC,OAAO,CAAC,CAAmB;gBAEvB,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAK9D;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoDzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,GACrB,gBAAgB;IA8EnB;;OAEG;IACH,OAAO,CAAC,YAAY;IAMpB;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIxD;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKpD;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAmB3C;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;CAUnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,KAAK,IAAI,EAC/D,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,KAAK,IAAI,CAqBrD"}