@principal-ai/principal-view-core 0.24.77 → 0.24.78

package/dist/workflow/edge-derivation.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Edge Derivation from Workflows
+ *
+ * Extracts span context from workflow event templates and derives
+ * expected edges (span transitions) for validation against spans.canvas.
+ *
+ * @see .principal-views/WORKFLOW-SPAN-INTEGRATION.md
+ */
+import type { WorkflowTemplate, WorkflowScenario } from './types';
+/**
+ * A derived edge representing a span transition observed in a workflow
+ */
+export interface DerivedEdge {
+    /** Source span name (exact) */
+    fromSpan: string;
+    /** Target span name (exact) */
+    toSpan: string;
+    /** Workflow file where this edge was observed */
+    workflowFile?: string;
+    /** Scenario ID where this edge was observed */
+    scenarioId: string;
+    /** Event names that caused this transition */
+    eventNames: string[];
+}
+/**
+ * Result of edge derivation from a single workflow
+ */
+export interface WorkflowEdgeDerivationResult {
+    /** Workflow name */
+    workflowName: string;
+    /** Root span for this workflow */
+    rootSpan: string | undefined;
+    /** All spans referenced in this workflow */
+    referencedSpans: string[];
+    /** Derived edges per scenario */
+    scenarioEdges: Array<{
+        scenarioId: string;
+        edges: DerivedEdge[];
+    }>;
+}
+/**
+ * Result of edge derivation across all workflows
+ */
+export interface EdgeDerivationResult {
+    /** All derived edges (deduplicated) */
+    edges: DerivedEdge[];
+    /** Per-workflow breakdown */
+    workflows: WorkflowEdgeDerivationResult[];
+    /** All unique spans referenced across workflows */
+    allSpans: string[];
+}
+/**
+ * Extract span context from a workflow's event templates
+ *
+ * @param scenario - Workflow scenario to analyze
+ * @param rootSpan - Default span for events without explicit span
+ * @returns Array of { eventName, span } entries in template order
+ */
+export declare function extractEventSpans(scenario: WorkflowScenario, rootSpan: string | undefined): Array<{
+    eventName: string;
+    span: string;
+}>;
+/**
+ * Derive edges from span transitions in event sequence
+ *
+ * Identifies when consecutive events are in different spans,
+ * which represents a potential edge (call relationship).
+ *
+ * Note: This captures temporal order, not parent-child nesting.
+ * We observe "span A was active, then span B was active" but
+ * cannot infer nesting without actual trace data.
+ *
+ * @param eventSpans - Event-span mappings in order
+ * @param scenarioId - ID of the scenario being analyzed
+ * @returns Array of derived edges
+ */
+export declare function deriveEdgesFromSequence(eventSpans: Array<{
+    eventName: string;
+    span: string;
+}>, scenarioId: string): DerivedEdge[];
+/**
+ * Derive all edges from a workflow template
+ *
+ * @param workflow - Workflow template to analyze
+ * @param workflowFile - Optional file path for tracking
+ * @returns Edge derivation result for this workflow
+ */
+export declare function deriveWorkflowEdges(workflow: WorkflowTemplate, workflowFile?: string): WorkflowEdgeDerivationResult;
+/**
+ * Derive edges from multiple workflows
+ *
+ * @param workflows - Array of { workflow, filePath } pairs
+ * @returns Combined edge derivation result
+ */
+export declare function deriveEdgesFromWorkflows(workflows: Array<{
+    workflow: WorkflowTemplate;
+    filePath?: string;
+}>): EdgeDerivationResult;
+/**
+ * Group derived edges by source and target for display
+ *
+ * @param edges - Derived edges to group
+ * @returns Map of edge key to list of workflows/scenarios containing it
+ */
+export declare function groupEdgesBySources(edges: DerivedEdge[]): Map<string, Array<{
+    workflowFile?: string;
+    scenarioId: string;
+}>>;
+//# sourceMappingURL=edge-derivation.d.ts.map

package/dist/workflow/edge-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-derivation.d.ts","sourceRoot":"","sources":["../../src/workflow/edge-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGlE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IAEjB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IAEf,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IAErB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAE7B,4CAA4C;IAC5C,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B,iCAAiC;IACjC,aAAa,EAAE,KAAK,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,WAAW,EAAE,CAAC;KACtB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,KAAK,EAAE,WAAW,EAAE,CAAC;IAErB,6BAA6B;IAC7B,SAAS,EAAE,4BAA4B,EAAE,CAAC;IAE1C,mDAAmD;IACnD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACtD,UAAU,EAAE,MAAM,GACjB,WAAW,EAAE,CAyBf;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,CAAC,EAAE,MAAM,GACpB,4BAA4B,CAuC9B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAClE,oBAAoB,CA+BtB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAAE,GACnB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAcnE"}

package/dist/workflow/edge-derivation.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Edge Derivation from Workflows
+ *
+ * Extracts span context from workflow event templates and derives
+ * expected edges (span transitions) for validation against spans.canvas.
+ *
+ * @see .principal-views/WORKFLOW-SPAN-INTEGRATION.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupEdgesBySources = exports.deriveEdgesFromWorkflows = exports.deriveWorkflowEdges = exports.deriveEdgesFromSequence = exports.extractEventSpans = void 0;
+const types_1 = require("./types");
+/**
+ * Extract span context from a workflow's event templates
+ *
+ * @param scenario - Workflow scenario to analyze
+ * @param rootSpan - Default span for events without explicit span
+ * @returns Array of { eventName, span } entries in template order
+ */
+function extractEventSpans(scenario, rootSpan) {
+    const events = scenario.template.events;
+    if (!events) {
+        return [];
+    }
+    const result = [];
+    for (const [eventName, eventTemplate] of Object.entries(events)) {
+        const explicitSpan = (0, types_1.isEventTemplate)(eventTemplate)
+            ? (0, types_1.getEventSpan)(eventTemplate)
+            : undefined;
+        // Use explicit span if provided, otherwise fall back to rootSpan
+        const span = explicitSpan ?? rootSpan;
+        if (span) {
+            result.push({ eventName, span });
+        }
+    }
+    return result;
+}
+exports.extractEventSpans = extractEventSpans;
+/**
+ * Derive edges from span transitions in event sequence
+ *
+ * Identifies when consecutive events are in different spans,
+ * which represents a potential edge (call relationship).
+ *
+ * Note: This captures temporal order, not parent-child nesting.
+ * We observe "span A was active, then span B was active" but
+ * cannot infer nesting without actual trace data.
+ *
+ * @param eventSpans - Event-span mappings in order
+ * @param scenarioId - ID of the scenario being analyzed
+ * @returns Array of derived edges
+ */
+function deriveEdgesFromSequence(eventSpans, scenarioId) {
+    const edges = [];
+    const seenEdges = new Set();
+    for (let i = 0; i < eventSpans.length - 1; i++) {
+        const current = eventSpans[i];
+        const next = eventSpans[i + 1];
+        // Transition occurs when spans differ
+        if (current.span !== next.span) {
+            const edgeKey = `${current.span}->${next.span}`;
+            if (!seenEdges.has(edgeKey)) {
+                seenEdges.add(edgeKey);
+                edges.push({
+                    fromSpan: current.span,
+                    toSpan: next.span,
+                    scenarioId,
+                    eventNames: [current.eventName, next.eventName],
+                });
+            }
+        }
+    }
+    return edges;
+}
+exports.deriveEdgesFromSequence = deriveEdgesFromSequence;
+/**
+ * Derive all edges from a workflow template
+ *
+ * @param workflow - Workflow template to analyze
+ * @param workflowFile - Optional file path for tracking
+ * @returns Edge derivation result for this workflow
+ */
+function deriveWorkflowEdges(workflow, workflowFile) {
+    const rootSpan = (0, types_1.getWorkflowRootSpan)(workflow);
+    const allSpans = new Set();
+    const scenarioEdges = [];
+    if (rootSpan) {
+        allSpans.add(rootSpan);
+    }
+    for (const scenario of workflow.scenarios) {
+        const eventSpans = extractEventSpans(scenario, rootSpan);
+        // Collect all referenced spans
+        for (const { span } of eventSpans) {
+            allSpans.add(span);
+        }
+        // Derive edges from transitions
+        const edges = deriveEdgesFromSequence(eventSpans, scenario.id);
+        // Attach workflow file to each edge
+        if (workflowFile) {
+            for (const edge of edges) {
+                edge.workflowFile = workflowFile;
+            }
+        }
+        scenarioEdges.push({
+            scenarioId: scenario.id,
+            edges,
+        });
+    }
+    return {
+        workflowName: workflow.name,
+        rootSpan,
+        referencedSpans: Array.from(allSpans),
+        scenarioEdges,
+    };
+}
+exports.deriveWorkflowEdges = deriveWorkflowEdges;
+/**
+ * Derive edges from multiple workflows
+ *
+ * @param workflows - Array of { workflow, filePath } pairs
+ * @returns Combined edge derivation result
+ */
+function deriveEdgesFromWorkflows(workflows) {
+    const allSpans = new Set();
+    const workflowResults = [];
+    const edgeMap = new Map();
+    for (const { workflow, filePath } of workflows) {
+        const result = deriveWorkflowEdges(workflow, filePath);
+        workflowResults.push(result);
+        // Collect spans
+        for (const span of result.referencedSpans) {
+            allSpans.add(span);
+        }
+        // Collect and deduplicate edges
+        for (const scenarioResult of result.scenarioEdges) {
+            for (const edge of scenarioResult.edges) {
+                const key = `${edge.fromSpan}->${edge.toSpan}`;
+                if (!edgeMap.has(key)) {
+                    edgeMap.set(key, edge);
+                }
+            }
+        }
+    }
+    return {
+        edges: Array.from(edgeMap.values()),
+        workflows: workflowResults,
+        allSpans: Array.from(allSpans),
+    };
+}
+exports.deriveEdgesFromWorkflows = deriveEdgesFromWorkflows;
+/**
+ * Group derived edges by source and target for display
+ *
+ * @param edges - Derived edges to group
+ * @returns Map of edge key to list of workflows/scenarios containing it
+ */
+function groupEdgesBySources(edges) {
+    const grouped = new Map();
+    for (const edge of edges) {
+        const key = `${edge.fromSpan}->${edge.toSpan}`;
+        const sources = grouped.get(key) || [];
+        sources.push({
+            workflowFile: edge.workflowFile,
+            scenarioId: edge.scenarioId,
+        });
+        grouped.set(key, sources);
+    }
+    return grouped;
+}
+exports.groupEdgesBySources = groupEdgesBySources;
+//# sourceMappingURL=edge-derivation.js.map

package/dist/workflow/edge-derivation.js.map

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

package/dist/workflow/edge-validation.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Edge Validation
+ *
+ * Validates derived edges from workflows against spans.canvas definitions.
+ * Ensures documented span relationships match observed workflow behavior.
+ *
+ * @see .principal-views/WORKFLOW-SPAN-INTEGRATION.md
+ */
+import type { ExtendedCanvas } from '../types/canvas';
+import type { DerivedEdge } from './edge-derivation';
+/**
+ * Span node info extracted from spans.canvas
+ */
+export interface SpanNodeInfo {
+    /** Node ID in the canvas */
+    nodeId: string;
+    /** Span pattern this node matches (e.g., "validate.*") */
+    spanPattern: string;
+    /** Human-readable name */
+    name?: string;
+}
+/**
+ * Canvas edge info extracted from spans.canvas
+ */
+export interface CanvasEdgeInfo {
+    /** Source node ID */
+    fromNodeId: string;
+    /** Target node ID */
+    toNodeId: string;
+    /** Source span pattern */
+    fromSpanPattern?: string;
+    /** Target span pattern */
+    toSpanPattern?: string;
+}
+/**
+ * Edge validation result
+ */
+export interface EdgeValidationResult {
+    /** Edges that are documented in spans.canvas and observed in workflows */
+    validEdges: ValidatedEdge[];
+    /** Edges observed in workflows but missing from spans.canvas */
+    missingEdges: MissingEdge[];
+    /** Edges documented in spans.canvas but not observed in any workflow */
+    unusedEdges: UnusedEdge[];
+    /** Spans referenced in workflows that don't match any spans.canvas node */
+    unmatchedSpans: UnmatchedSpan[];
+    /** Summary statistics */
+    summary: {
+        totalDerivedEdges: number;
+        totalCanvasEdges: number;
+        matchedEdges: number;
+        missingEdges: number;
+        unusedEdges: number;
+        unmatchedSpans: number;
+    };
+}
+/**
+ * An edge that passed validation
+ */
+export interface ValidatedEdge {
+    /** Source span name (exact) */
+    fromSpan: string;
+    /** Target span name (exact) */
+    toSpan: string;
+    /** Canvas edge it matched */
+    canvasEdge: CanvasEdgeInfo;
+    /** Workflows where this edge was observed */
+    sources: Array<{
+        workflowFile?: string;
+        scenarioId: string;
+    }>;
+}
+/**
+ * An edge observed in workflows but missing from spans.canvas
+ */
+export interface MissingEdge {
+    /** Source span name */
+    fromSpan: string;
+    /** Target span name */
+    toSpan: string;
+    /** Source span matched to this node (if any) */
+    fromNodeId?: string;
+    /** Target span matched to this node (if any) */
+    toNodeId?: string;
+    /** Workflows where this edge was observed */
+    sources: Array<{
+        workflowFile?: string;
+        scenarioId: string;
+    }>;
+    /** Reason this edge is missing */
+    reason: 'no-edge-in-canvas' | 'span-not-matched';
+}
+/**
+ * An edge documented in spans.canvas but not observed in workflows
+ */
+export interface UnusedEdge {
+    /** Canvas edge */
+    canvasEdge: CanvasEdgeInfo;
+    /** Canvas file where this edge is defined */
+    canvasFile?: string;
+}
+/**
+ * A span referenced in workflows that doesn't match any spans.canvas node
+ */
+export interface UnmatchedSpan {
+    /** Exact span name from workflow */
+    spanName: string;
+    /** Workflows that reference this span */
+    sources: Array<{
+        workflowFile?: string;
+        scenarioId: string;
+    }>;
+}
+/**
+ * Extract span nodes from a spans.canvas file
+ *
+ * @param canvas - Parsed spans.canvas content
+ * @returns Array of span node info
+ */
+export declare function extractSpanNodes(canvas: ExtendedCanvas): SpanNodeInfo[];
+/**
+ * Extract edges from a spans.canvas file
+ *
+ * @param canvas - Parsed spans.canvas content
+ * @param spanNodes - Map of nodeId to span info
+ * @returns Array of canvas edge info
+ */
+export declare function extractCanvasEdges(canvas: ExtendedCanvas, spanNodes: SpanNodeInfo[]): CanvasEdgeInfo[];
+/**
+ * Match an exact span name to a span pattern
+ *
+ * @param spanName - Exact span name (e.g., "validate.canvas")
+ * @param pattern - Span pattern (e.g., "validate.*")
+ * @returns true if the span matches the pattern
+ */
+export declare function matchSpanToPattern(spanName: string, pattern: string): boolean;
+/**
+ * Find the canvas node that matches a span name
+ *
+ * @param spanName - Exact span name
+ * @param spanNodes - Available span nodes
+ * @returns Matching node info or undefined
+ */
+export declare function findMatchingNode(spanName: string, spanNodes: SpanNodeInfo[]): SpanNodeInfo | undefined;
+/**
+ * Check if a derived edge has a corresponding canvas edge
+ *
+ * @param derivedEdge - Edge derived from workflow
+ * @param canvasEdges - Edges from spans.canvas
+ * @param spanNodes - Span nodes from spans.canvas
+ * @returns Matching canvas edge or undefined
+ */
+export declare function findMatchingCanvasEdge(derivedEdge: DerivedEdge, canvasEdges: CanvasEdgeInfo[], spanNodes: SpanNodeInfo[]): CanvasEdgeInfo | undefined;
+/**
+ * Validate derived edges against spans.canvas
+ *
+ * @param derivedEdges - Edges derived from workflows
+ * @param canvas - Parsed spans.canvas content
+ * @param canvasFile - Optional file path for tracking
+ * @returns Validation result
+ */
+export declare function validateEdges(derivedEdges: DerivedEdge[], canvas: ExtendedCanvas, canvasFile?: string): EdgeValidationResult;
+/**
+ * Format validation result as human-readable text
+ *
+ * @param result - Validation result
+ * @returns Formatted string
+ */
+export declare function formatValidationResult(result: EdgeValidationResult): string;
+//# sourceMappingURL=edge-validation.d.ts.map

package/dist/workflow/edge-validation.d.ts.map

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